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IMPORTANT NOTE: This document is evolving toward being a complete MEDA 

s Programmer's Guide, but it is not yet there! Some reference to external 
example files and information will be necessary to create a new module from 
scratch. 


The reader of this document is assumed to understand general Macintosh 
' programming concepts, including: 


¢ Window operation 

* Menu operation 

* Quickdraw 

* User events 

* Resources 

* Memory management 


Introduction to MEDA ™ 


The MEDA (Modular Electronic Design Application) concept arises from the 
desire to create an environment in which independently-developed electronic 
design functions can operate in an integrated and interactive fashion. This 
benefits users by allowing them to work in a consistent environment and giving 
them painless access to a variety of special-purpose packages. In addition, it 
allows Capilano Computing, independent software developers, and users with 
programming capability to add specialized, yet fully integrated, functions to 
DesignWorks. 


Example application modules that are well suited to this concept are: 


* new simulation models for the existing simulator 

* a complete, new simulation module, such as analog circuit simulation 
¢ interfaces to external simulation hardware 

* various types of circuit analysis, such as timing analysis and fault analysis 
* back annotation 

* logic synthesis, generating net list or PLD code output 

« integrated PCB or chip layout 

* schematic generation from net lists 

* control of external instrumentation, such as logic analyzers, digital 
oscilloscopes, pattern generators, etc. . 

* novel ways of displaying simulation data 


The MEDA Concept 


in the MEDA concept, a central application, referred to as the "Gatekeeper" 
makes available general services, such as: 


* time sharing 

* general circuit drawing facilities 

« window management 

* menu management 

* debugging facilities, such as a message window 


In addition to the services provided by the Gatekeeper, client modules can be 
simplified given that related functions can be provided by other clients. For 
example, all the schematic entry and simulation functions implemented in 
DesignWorks are available through the MEDA interface, including the ability to 
query or modify circuit connectivity, attributes, simulation information, etc. This 
means that modules requiring circuit editing or simulation functions can make 
use of the existing ones rather than having to re-implement them. 
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MEDA Inter-Module Communications 


Report 
Generator 
Utility 
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Client modules communicate with the Gatekeeper or with each other via a 
message-passing scheme. A simple time-sharing task manager is 
implemented allowing the modules to coexist under the current single-task 
Macintosh operating system, but the communications scheme is designed with 
multi-tasking and multi-processing in mind. 
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As the above diagram shows, the major functional parts of DesignWorks are 
internally implemented as MEDA modules, even though they are combined into 
a single file in this release. Other functions, such as the Report Generator, are 
implemented in separate files. In either case the communication method is the 
same. 


Example Application 
The I/O Panel module, included with DesignWorks, demonstrates the ability to 


interactively access circuit and simulation information. It demonstrates the 
following MEDA capabilities: 


* its function is invoked by a menu item 

* it creates and maintains a data-entry window which can be kept visible 
while other circuit operations are performed 

* the current circuit is searched for signals of a given name 

* the simulator notifies the I/O Panel module each time one of its displayed 
signals changes in value 


The i/O Panel was created independently of DesignWorks and has no 
knowledge of its internal formats. All data is accessed through the MEDA 
interface. 


Creating MEDA Modules 


MEDA modules are written using standard Macintosh programming languages 
using the Macintosh Programmer's Workbench (MPW) or ThinkC systems. The 
MEDA Developer's Kit package contains interface libraries and example files. 





nstalling th 

The following files/folders are included with the Developer's Kit. Note that when 
we specify a location on your hard disk for one of these items, this is only a 
suggestion. By judicious modification of pathnames and MPW variables you 
can place the files anywhere on the disk. We will assume you have an 
understanding of your own development environment to make these 
modifications. 


Support is included in this release for MPW C and ThinkC. In theory it is 
possible to interface with other languages by developing appropriate interface 
routines, however this is a significant project and not recommended. Contact us 
directly before proceeding. an 


MPW Version 


This is a folder containing run-time libraries and header (".h") files needed when 
compiling and linking a module. There will inevitably be a few headaches 
involved in getting the library folders located correctly, but once this is done 
modules should compile and link very smoothly. 


A typical folder setup for MPW will look like this (obviously most of the standard 
MPW files have been omitted for clarity): 


ea MPW Folder —$—~———____ 


Interfaces | Libraries 
Be 


_) 


MED Alnterfaces wee: MEDA a MED ALibraries CLibraries 


rai 
= 
YourModule Designworks™ 2.5.3b4 


DevEditor 
ListNet Example - MP 


Lib! 
Your Project Folder 





MEDALibrari 


The MEDALibraries folder should be placed in the same folder containing the 
aie runtime libraries used by the MPW C compiler, generally called 
“Libraries”. 


The MPW shell variable "MEDALibraries" should be set to point to the folder 
containing these files in order for the supplied sample "make" files to work. This 
can be set up in your “UserStartup" file so you don't have to think about it again. 
The text for this will look like the following, unless you have deviated from the 
standard folder setup for MPW: 


export MEDALibraries 
set MEDALibraries "({MPW}Libraries :MEDALibraries:” 


Files in the MEDALibraries folder include: 


* MEDA.0 is the general MEDA interface library. 

* MEDACodePre.o is a header file that must be linked to any MEDA module 
using multiple CODE resources. 

* MEDADrvrPre.o is a header file for single-code-resource DRVR-type 
modules. 


It will not be necessary to completely understand the functions of these files as 
long as you start from one of the sample "make" files provided. 


MEDAInterfaces 


This is a folder containing the header files accessed by the C compiler while 
compiling any program that imports MEDA functions. The contents of this folder 
should be placed in the same one containing the general Mac interface routines 
used by the C compiler, generally called "Interfaces". The MPW shell variable 
"MEDAlInterfaces" should be set to point to this folder. As noted above, this can 
be set up in your UserStartup file as follows: 


export MEDAInterfaces 
set MEDAInterfaces °{MPW} Interfaces :MEDAInterfaces:" 


ThinkC Version 


In order for the ThinkC system to correctly locate the MEDA libraries, they 
should be located in the same folder as the other system libraries. This is 
normally the one called "ThinkC Folder". The procedure is then simply to copy 
the folder "MEDA Libraries" (Note: this is not the same one as "MEDALibraries' 
in the "MPW Version" folder) into "ThinkC Folder". ThinkC automatically looks 
inside every library folder to locate include files. 


When creating a new ThinkC project, it will be necessary to "add" the library 
"MEDA‘ to your project in order to resolve the MEDA names. 


The ThinkC versions of the libraries are identical to the MPW ones and ail 
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differences are “ifdef'ed using constants defined in the file MEDASystem.h. 


MEDA 


This folder is the general development folder for MEDA modules. It contains the 
a number of example files and the version of DesignWorks required to work with 
the MEDA modules. Some of the examples files may contain "ifdef's to account 
for the slight differences between MPW C and ThinkC. 


Example Files 


ListNet 


"ListNet" is a module that allows a user to display a list of the pin connections 
making up a given named net in the current circuit. It demonstrates the 
following MEDA functions: 


* initialization 

* creating and displaying a window 

* using a window as a non-modal dialog box (i.e. the user can switch to other 
windows without leaving the dialog). 

* accessing circuit connectivity information, including device and signal 
names, pin lists, etc. 


0 ; f the List ul 
¢ select the ListNet item from the Module menu. The following dialog box 
appears (the signal name box will be empty initially: 


Signal Name 


Ji-5 U1-1 





* type the name of a signal in the currently open circuit, then click on the 
"List" button or hit the return key. 


« a list of the device pins attached to the named signal will be displayed in 
the lower part of the box. 


* the box is "non-modal" (to use Apple terminology), meaning that the 
window can be left displayed while working in other windows. 


« this module does not attempt to perform all the functions included in the 
Report module that comes with DesignWorks. In particular, it does not: 


¢ display any net string over 255 characters. 
* extract power and ground connections from device user info. 
* auto-number pins on discrete componenis. 


Model6809 


This examples demonstrate the creation of MEDA simulation models, in 
particular the following MEDA capabilities: 


¢ simulation notification requests 
* accessing and setting simulation values 
* communitcation between modules. 


Be sure to read the "Read Me" files and source code comments in the example 
files. 
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Module User interface 


Asleep vs. Awake vs. Active 


A MEDA module can be in one of three states: asleep, awake and active. Each 
of these states has a different effect on the user interface and on the internal 
programming environment. A module can change it's status from asleep to 
awake under program control when it thinks its function is being invoked or has 
completed. Any number of modules can be awake. The "active" state is 
reserved for a single module, generally the owner of the frontmost window on 
the screen. The active module is selected by the user from among the awake 
ones by clicking in one of its windows, or by selecting it in the Modules menu. 


Asleep 


From a user's point of view, when a module is asleep, it has the following 
characteristics: 


* any menu items it displays are unhilited. 
¢ its menu item in the Modules menu is unchecked. 


From a programmer's point of view, the asleep state has the following additional 
effects: 


¢the module's code can be unloaded by the GateKeeper if it runs out of 

memory. This will generally not affect the module as long as you don't rely 
on some procedure being in a particular place. (NOTE: Code unloading is 
not implemented in the current version of DesignWorks, but may be at any 


moment.) 
¢ the module will receive no Mb (menu before) or li (idle) messages. 


Although the GateKeeper does not enforce this, a module should only set itself 
to asleep when all its windows are closed and all user-visible functions are 
complete. 


See the description of the library routine "MEDASetAwakeStatus". 
Awake 


When a module is awake it's entry in the Modules menu is checked and its 
menu items may be active, depending on various status settings. The module's 
code is locked in memory and the module will receive any "Mb" or "li" 
messages. 


Active 


Only a single module can be active at any one time. The currently active 
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module also is considered to be "awake" in that it has the characteristics noted 
above for "awake" modules. in addition, the active module is the first one 
notified of any menu selections and the one to which any window events are 
directed. 


The GateKeeper maintains a list of all modules in the system and the order in 
this list determines how some functions such as menu enabling will appear to 
the user. Whenever a module (say ModuleA) is activated (i.6. its window is 
brought to the front, etc.) that module is moved to the front of the list. This 
means that it gets first chance to intercept any menu hits and to control the 
status and appearance of menu items. If ModuleB is now activated, the new 
one is moved to the front and ModuleA will be second in line. More information 
on the menu mechanism is given below. 


Internally, only one event causes a module to be made “active": a window being 
brought to the front. When the user selects a module in the "Module" menu, this 
does not itself make the module active, but merely signals the module to create 
or select a window, which in turn will cause a system window activate event, 
which signals to the GateKeeper to activate the owning module. 


Initialization 


When the GateKeeper is started by the user it loads and initializes all available 
MEDA modules. From the user's point of view, most of this process is invisible 
except for the time it takes and the following side effects: 


* any menus added by modules will appear in the menu bar. 
* the progress box displays the name of the module being loaded. 


After all modules are loaded and initialized, any modules that set the "awake on 
startup" flag in response to the "Im" message will be "woken up". What this 
means exactly depends on the module, but in general it will cause a window to 
be displayed. In DesignWorks, uniess there's some good reason for doing 
otherwise, modules should not set this flag since it will result in a profusion of 
windows appearing at startup. Normally, the only reasons for being woken up 
at startup are: 


* you are implementing a function that replaces the DesignWorks circuit 
drawing windows as the main startup function. 

* your module performs some background task that should be active all the 
time (i.e. you don't want it to be unloaded) and it does not display a window. 


Menu Operation 


The MEDA system allows whole menus or individual menu items to be shared 
by modules. In order for this to work, rules have been established about who 
gets access to a given menu item at any time. 
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Menu. Enabling 
Under normal circumstances, only menu items associated with the "active" 
module are enabled. This means that the user can only invoke functions that 


will affect the topmost window. There are some occasions when it is desirable 
to have other items enabled, as follows: 


¢ the "Quit" and "Transfer" items in the File menu, as well as the "Window" 
and “Module" menus, are handied directly by the GateKeeper are always 
enabled. 

* a module can specify that an item should be “enabled while inactive", 
meaning that it will be enabled even if that module is not the "active" one. 
This is generally confusing to the user and should be avoided, but within 
DesignWorks, some items such as "Save" and "Open" are given this status. 


Menu Selection 

When a menu item is selected by the user, the GateKeeper runs down the list of 
modules, starting with the "active" one to see if any modules have associated 
with the given item. (See the comments on order in the module list under 
"Active Module", above.) If the active module has not registered the given menu 
item, then the next module on the list is checked. When the module associated 
with the given item is found, it is sent the menu select message and it performs 
the desired function. From the user's point of view, this means that a function 


associated with some buried window can be invoked, which is generally 
undesirable. 


Module Menu 


The Module menu is handled directly by the GateKeeper and is always 
enabled. From the user's point of view, selecting a module from this menu 
should cause the module to make itself visible, either by creating a new, untitled 
window, or by displaying an existing, untitled window. Internally, the only effect 
of selecting an item in this menu is that the module is sent an "lw" (wakeup) 
message. The module should then respond by doing appropriate things with its 
windows. Note that the act of selecting the module in this menu does not in 
itself make the module the “active one. It becomes “active” when the 
GateKeeper receives a window activate event for the module's window. 


Module 


Attributes 
DevEditor 
/“ Drawing 
ErrorFind 
1GPanel 
Report 
“Timing 










Ee ee 


In a typical Module menu, ail "awake" modules are marked with a check, and 
the "active" module is underlined. 


Window Menu 


The Window menu is handled by the GateKeeper and lists ail windows owned 
by all modules (assuming they were added using the "MEDAAddWindow" call). 
When the use selects one of these items, the GateKeeper calls the Mac toolbox 
routine SelectWindow, which will indirectly result in a window activate message 
being sent to the module. 
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Communication Between Modules 


General 


General notes 


* every module has a single entry point, which is its "Receive Message" 
procedure. This procedure takes a single argument (using standard 
Macintosh calling conventions) which is a pointer to the message record. 

* no module ever calls another module directly (i.e. by calling to an address 
inside the other module's code) and attempting to do so will cause great 
confusion in the GateKeeper. Messages are passed by calling the library 
routine MEDASendMessagein MEDADefs which calls the GateKeeper, 
which then decodes the message type and destination address and either 
services the message itself or passes it on to another module. 

* the message record starts with a number of fields, such as the message 
type and destination address, which must be present, then may contain an 
arbitrary collection data fields appropriate to the message meaning. 

* in most cases, unless a module implements a new message type, it will not 
access the message record directly, but simply call library routines which 
then fill in and transmit the message structure. 

* the message structure is passed by address, so any fields can be filled in 
or modified by either the source or destination modules. 


estination 


Most MEDA functions are activated by calling the appropriate MEDAxoox« library 
routine. These routines are responsible for creating and filling in the message 
record, so most programmers will never need to create one from scratch. 
However, for cases requiring direct communication between modules, there are 
two ways of addressing a message: 


1) A message can be addressed to a specific module by placing that 
module's address in the "destModule" field of the message header. In this 
case, the GateKeeper passes the message directly to the specified module 
without any further examination of the message type or contents. A module 
address can be obtained by looking up the module by name or message 
type, or by retaining the address returned when the module is loaded. 


2) If the "destModule" is NIL, then the GateKeeper looks at the first character 
of the message type field. This letter is compared to the internally-defined 
GateKeeper functions (e.g. window, menu and initialization) then to the 
message type accepted by each server module (i.e. as returned in response 
to the "Im" message). When a match is found, the message is passed to that 
module. If not match is found, the GateKeeper displays an error box. To 
avoid the error box, you should check that the message class is valid before 
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sending the message. This is done by calling the "available" routine in each 
library (e.g. "MEDACircuitAvailable" in library "MEDACircuit"), or by looking 
up the module by message type, using the routine 
"MEDAFindModuleByMsg". - 


Initialization 
All communication is initiated by the GateKeeper, as follows: 


« the GateKeeper looks for all files of a specified type in its folder. 

* any suitable files found are opened and the main code segment isloaded 
into memory. 

* the main code segment is assumed to be a procedure of the form given 
below, and is called with an Initialize Module (Im) message. This message 
contains the return entry address for calls from the module to the 
GateKeeper. 

* the module does any required initialization, such as setting up windows or 
menus (which may involve calls to the GateKeeper), then returns. 

* the GateKeeper now enters its main event loop, polling all modules each 
time around the loop by sending an idle message. Any user activity in a 
menu or window belonging to a module will result in an appropriate 
message being sent to that module. 


Message Procedure Header 


The main entry point to the module and the return entry point to the GateKeeper 
are assumed to be functions of the following form: 


pascal void Message(tMsg *pMsg); 


"msg" is a parameter record as defined below. The "tMsg" record definition 
contains fields for all message types defined in the current DesignWorks. The 
"tMsg" record is given only as a convenience to ensure compatibility with the 
GateKeeper. You can define your own record structures for records as long the 
fields are in the same relative positions defined below. Since the message is 
passed as a VAR parameter, ail that is really passed is a pointer to a block of 
memory. The first two characters of this block must be the message code, the 
rest are dependent on the message type. 


Client vs. Server Modules 


For the purposes of the following documentation, a distinction is made between 
"Client" and "Server" modules. [In general, a “ciient" is the module initiating a 
message and the "server" is the one taking the requested action or returning the 
desired data. However, this definition is not sufficient because the notification 
mechanism can cause messages to be sent in the reverse direction between a 
client and server. In MEDA, we define the "server" module to be the one which 
defines the first letter of the message command field, i.e. the one that specified 
this letter in its "imMessageType" field during initialization. 
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For example, the DesignWorks drawing module implements the "C" messages, 
so it is considered the server in any "C" message, regardless of direction. 


Even though it is not strictly a module, the GateKeeper is considered to be the 
server in any initialization ("I"), window ("W"), menu ("M") or debug ("D") 
message. 


Notification Mechanism 


In a normal case, a client module creates a message and sends it to a server to 
request some information or action. The server performs the requested action 
and returns. In many cases, however, it is desirable for a client module to ask to 
receive a message at a future time when some specific condition or event 
arises. This allows the client module to be dormant, not occupying CPU time 
until some action is required. In MEDA, this kind of reverse message is called a 
“notification”. The notification mechanism is used within DesignWorks for a 
number cases: 


e whenever a module creates a window, the GateKeeper uses the 
notification mechanism to send a message to the module whenever an 
action (such as mouse down, key pressed, update, etc.) occurs on that 
window. Many of these notifications correspond to Macintosh Toolbox 
events. 

¢ the DesignWorks drawing module allows a client to request notification 
whenever an object of a given type is created, deleted, or changed. 

* the DesignWorks simulator allows a module to request notification on value 
changes for a given signal or device. 


The MEDA message format allows any module to direct any message to any 
other module, so in fact the server module developer is free to implement any 
notification structure desired. However, some notification support is provided in 
the GateKeeper so, for the sake of standardization and efficiency, it is best to 
use the standard format. 


GateKeeper Notification S 


The notification support is set up to support situations where a server module 
creates and maintains objects (e.g. windows, signals, graphics objects, etc.) 
which have operations performed on them. The server needs to be able to 
accept requests for notification when a certain type of change occurs on a 
specific object or class of objects. 


The GateKeeper assists in setting up a notification structure by maintaining lists 
of destination modules for the server. This allows the server to accept an 
arbitrary number of notification requests on the same object with very little extra 
overhead. For each object in the server that might generate a notification event, 
the server needs only keep a single pointer, regardless of how many client 
modules have asked for notification on that object. For each module on the 
destination list, the GateKeeper records the following information: 


oe hy ae 


«the address of the destination module 

* a "refCon" reference value supplied by the client module making the 
request. This will be placed in the “objRefCon" field of any message 
transmitted to the client as a result of this notification. This can be used by 
the client to point to its own internal data corresponding to the server's 
object. 

* a "mask" value which lists what notification messages the client wishes to 
receive. For example, a certain client may be only interested in a notification 
when a device of a certain type is created or deleted in DesignWorks. The 
client module will be attached to the list, but its mask will specify that only 
create and delete messages are accepted. The Gatekeeper checks the 
second character of the notification message against the mask string and 
only forwards the message if a match is found. 

*a'chain" flag. (NOT IMPLEMENTED YET!) This is used to allow the server 
to create lists in which a message is sent only to the first client that accepts it, 
not to all clients on the list. In a normal, non-chain list, the notification 
message will be sent to all clients on the list before returning to the server. 
Chained lists are described in more detail below. 


The following table summarizes the actions that occur in the notification system. 


Initlalization or Server initializes 
object creation pointer to list head to 
NiL 


Client requests Client sends message 
notification to server specifying 
the object or class of 
interest, refCon value, 
and message mask 











































GateKeeper adds a 
destination record to 
the list, stores the 
module address, 
chain flag, refCon and 
mask, and returns an 
updated list pointer. 


Server sends a 
message to 
GateKeeper with a 
pointer to the existing 
list for this object 
(possibly NIL), client 
module address, 
chain flag, refCon and 
mask. 
GateKeeper receives 
message and checks 
it against each item on 
the destination list. If 
the message type is 
found in the mask, it 
fills in the objRefCon 
and dstModule fields 
and transmits the 
message to the client. 
Server performs any 
internal action needed 
and sends “delete 
destination” message 
to GateKeeper. 














































Client receives 
message, performs 

appropriate action and 
returns. 


Server creates a 
message record 
containing any 
desired information on 
the object in question, 
fills in the "dstModule" 
field with the list head 
pointer, and sends 
the message. 


Notification event 
occurs In server 



































GateKeeper removes 
item from list and 

returns updated list 
head pointer. 


Client sends 
“unrequest” message 
to server. 


Cllent removes 
notification 
request 
























NOT IMPLEMENTED YET! 


-18 - 


Message format 


A message is an arbitrary-length string of bytes starting with a 2-byte message 
type. The message type will normally be 2 ASCII characters, for ease of 
debugging. Arguments are of a fixed length so no separators are required. 


Message Record Definition 


Following is the record definition for all possible message formats. This is done 
only for type-checking convenience. Separate records could be defined for 
each message type, or data could be assembled in a binary string, as desired. 


(see file MEDADefs.h) 


Message Types 


Each message starts with a two character code that defines its message type. 
The first character determines which module will receive the message and the 
second character determines the specific function of the message. Following 
are the general message types currently in use (or reserved) in the 
DesignWorks/MEDA system, as determined by the first character of their codes: 


First char {implementing Module Function 


| Gatekeeper Initialization/module management 
W Gatekeeper Window management 

M Gatekeeper Menu management 

D Gatekeeper Debugging 

Cc DesignWorks Circuit data operations 

Ss DesignWorks Simulation data operations 

T DesignWorks Timing diagram operations (not imp) 
E Editor Text editor operations 

R Report Report generator operations 

L LiblO Device library operations 


All other upper-case letters are reserved for use by Capilano Computing. User- 
defined modules should use a lower-case letter or non-alphabetic character. 


A module can offer services to other modules by specifying (in response to the 
"Im" message, see the "MEDAInitMessage" procedure) the first letter of the 
commands it is willing to receive. The contents of the balance of the message 
record are be completely defined by the module. 


Message Direction 


When a message is defined as “from Module" this means it is expected to be 
passed as an argument in a call from a module to the GateKeeper. Messages 
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defined as "to Module" are expected to be received as an incoming argument to 
the module's message entry point. 


Similarly, individual fields within a message may have a direction associated 
with them, as follows: 


<- 


“> 


<> 


Fields that are to be filled in by the client module (i.e. data 
flow is away from the client) 

Fields that are to be filled in by the GateKeeper or Server 
module (i.e. data flow is toward the client module) 
Bidirectional (i.e. set by the originator, then modified by the 
receiver before returning) 

Fields that are filled in by the originator (source) of the 
message, regardless of whether it is the client or server. 
Fields that are filled in by the destination of the message, 
regardless of whether it is the client or server. 

Fields that are filled in by the GateKeeper every time the 
message is sent. 


Fields Common to All Messages 


A number of message fields are filled in or used by the GateKeeper and must 
be common to all messages. 


PODDNDAM 


a. 
msg Type 
srcModule 


dstModule 


dstRefCon 


msglype : tMsgType; 
modVers : short; 
srcModule : Ptr; 
dstModule : Ptr; 
dstRefCon : Ptr; 
objRefCon : Ptr; 
handied : Boolean; 
spare : Boolean; 


is a two-character string identifying the type of the message. 

is the address of the source module. This is filled in by the 
GateKeeper whenever any message is passed. When a message 
originates from the GateKeeper, this will be NIL. 

is the address of a single module or a list of destination modules 
created using the notification mechanism. If the originator of the 
message fills in a non-NIL value then the message is sent to the 
addressed module regardless of message type. If a NIL value is 
specified, the GateKeeper looks up the appropriate server by the 
first character of the "msgType" field and fills in the destination 
address. 

is a reference field which can be specified by the client module on 
initialization, and is filled in automatically by the GateKeeper for 
every subsequent message directed to that module. This can be 
used, for example, to store a pointer to some global data which will 
then always be available to the module whenever it receives a 


objRefCon 


modVers 


handled 


spare 
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message. 
is another reference field, but this one is specific to the notification 
mechanism. Whenever a module requests notification from any 
other module, it can specify a "refCon" value to be filled in when 
that particular type of event occurs. For example, this can be used 
with window event notifications to hold a pointer to the module's 
internal window information. 

is a constant integer value which is placed in every message by 
the MEDA library routines. This is used by the GateKeeper to 
check the validity of a message and by the server module to check 
the version of the jibraries that was used to create the message. 
Most of this checking is currently not implemented, but this field 
will be needed to ensure compatibility with future versions. 

is a boolean value that specifies whether the receiving module 
performed the action requested. This is currently not 
implemented. 

is a byte which is currently unused but is reserved for future use. 


sos 


Programming Notes 


The MEDA module is not a stand-alone program but runs as part of the 
DesignWorks application. Following are some important facts about the 
environment that the MEDA module sees. 


Memory Management 
Heap and Stack Usage 


The MEDA module is operating essentially as a subroutine of the main 
program, meaning that it shares the available stack and heap space with the 
main program and the other loaded modules. The module should avoid doing 
strange things to expand and contract the heap and stack as this may have an 
adverse affect on other modules. The module is free to use the Memory 
Manager calls NewPtr, NewHandle, etc. to allocate memory. It is the module's 
responsibility to deallocate anything it allocates; the Gatekeeper does not touch 
memory allocated by a module. 


iMPORTANT: if you use any compiler-specific memory allocation functions such 
as C's "malloc", be aware that each module is working with a completely 
independent allocation system. A block that is allocated by one module cannot 
in general be deallocated by another one. In particular, never use any of these 
functions to create or destroy any DesignWorks circuit elements. The only way 
to allow cooperative creation and deletion of memory blocks is to use the 
toolbox routines NewHandle, DisposHandle, NewPtr, DisposPtr, etc. 


viron d Glo t 


In order to implement the run-time loading of modules, each module has its own 
"A5" environment, meaning that the module's jump table and global data are 
separate from all other modules. The module's global data is static, meaning 
that variables in the outermost scope of the module will stay intact throughout 
the execution of the main program, even if the module goes to sleep and it's 
code is unloaded by the GateKeeper. 


Code Segment Loading 

A module's code segments are loaded and locked in memory as long as the 
module is awake, i.e. after receiving an "Iw" message, and before sending an 
"A". In addition, if a message is sent to a module that is not awake, its code will 
be loaded and locked until it returns. Upon return, the GateKeeper will mark it 
as unloadable, unless it has in the meantime sent a message saying it is going 


to stay awake. To cut down on loading and unloading activity, a module should 
mark itself as awake if it expects to be receiving messages from other modules. 
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Resource Access 


Resource Files 

Whenever a message call is made to a module, the Toolbox routine UseResFile 
is called with the file ID of the module's resource file. This will normally ensure 
that the module's resources are available for loading as in a normal application. 
If the module opens any resource files other than itself it must always call 
UseResFile immediately before attempting to access resources, since the 
resource file list is modified after every pass though the GateKeeper (even by 
debug messages)). 


Resource Numbering 

it is normally not a problem if two module files contain resources having the 
same type and resource ID due to the resource file setting discussed above. 
However, it is strongly recommended that this situation be avoided in case of 


compatibility problem with future versions of DesignWorks and the Macintosh 
Operating System. 


It is the module developer's responsibility to ensure that resource ID's used in 


the module do not conflict with any other modules. This restriction does not 
apply to CODE segments, since they are loaded under special circumstances. 


We suggest using the following conventions: 


0 - 3999 Reserved for internal DesignWorks use 
4000 - 7999 Other Capilano development 

8000 - 15999 Third party developers 

16000 - 32767 End users 


User Events 


In order to arbitrate between a variety of MEDA modules, each of which may 
accept input from the user at any time, the Gatekeeper takes user events (e.g. 
mouse button up/down, key up/down, window updates, etc.) off the system 
event queue and determines which MEDA module should receive them. These 
are converted to MEDA notification messages and sent to the appropriate 
module(s). In most cases, the module owning the frontmost window receives 
the message. 


The equivalence between Mac events and MEDA notifications is as follows: 


Mac Event MEDA Message 
Update window Wu 
Activate window W+ 
Deactivate window W- 


Mouse button pressed Wop 
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Mouse button released Wr 
Key pressed Wk 
Null WdWilli 


Note that a pointer to the original Macintosh event is passed in the "wEvent" 
field in all window notifications for cases where a toolbox routine requires an 
event, such as DialogSelect. 


In addition, some higher level processing is done on mouse down events so 
that many common functions are handled automatically by the GateKeeper 
without the intervention of the module. These functions include: 


* window resizing/zoom (Wz message) 
* scroil bars and controls (Ws message) 
* window close box (Wc message) 

* menus (M messages) 


The module should normally not call the Mac routine 
GetNextEvent/WaitNextEvent except for modal dialog boxes. It is important that 
the GateKeeper get first chance to look at all events to detemine if they could 
affect any other module. 


Note Regarding System 7.0 

To support an interface using Macintosh System 7.0 "high level events", the 
module can request a notification each time a high level event is received by 
the GateKeeper. The notification includes a pointer to the event structure which 


can then be examined and handled as needed by the module. See the 
"MEDAInitMessage" routine and the "Ih" notification message. 


Window Handling 


The GateKeeper implements a number of high-level window management 
functions in order to arbitrate between the modules, provide a consistent user 
interface and simplify the module code. These functions include: 


* handling the Windows menu allowing the user to bring any open window 
(belonging to any module) to the front. 

* automatic handling of window moving and resizing. 

* detection of window close box hits. 

* handling of scroll bar and control hits. 


We strongly recommend that you make use of these window functions in order 
to ensure correct and consistent program operation. 


Creating a New Window 
The GateKeeper provides no particular support for the initial creation of a 


window. A window structure must be created in the same manner as for a 
stand-alone program using "GetNewWindow", "GetNewDialog", or other 


-24. 


appropriate Mac Toolbox calls. Similarly, any scroll bars or other controls 
should be added to the window before calling the GateKeeper. 


Once the window structure is completely set up, the MEDA call 
"MEDAAddWindow" should be called. This tells the GateKeeper to insert the 
given window in the Windows menu and add it to the list of windows it knows 
about. After this call, the module must be prepared to receive "Wx" notification 
messages for updates, activates, mouse activity, etc. 


Window Acti 


Most standard window actions, such as activating, moving, resizing, closing, etc. 
are intercepted by the GateKeeper which performs all appropriate hiliting and 
user interaction. After the action is completed from the user's point of view, a 
notification message is sent to the module, as follows: 


After close box hit We 

After resize or zoom box hit Wz 

After scroll or control hit Ws 

After activate W+ (see note below) 
After window moved none 


Note: The activate message is generated in response to the Mac activate event 
which will occur after a window is brought to the front. 


Not fing dist 


"Modal" dialogs (i.e. those that beep when you click outside the window) can be 
handled directly by the module in the usual way since no interaction with other 
modules is possible while the dialog is up. "Non-modai" dialogs (i.e. those that 
allow you to switch to other windows while they're open) must be registered 
with the GateKeeper as windows in order to interact correctly with the rest of the 
system. 


Menu Handling 


The GateKeeper implements a menu-handing scheme that allows modules to 
create their own menus, add items to existing menus or even share the same 
menu items with other modules without any knowledge of one another. 


Creating Menu Items 
Menu items can be added to the existing set in one of two ways: 


« the library routine "MEDAAddMenultem'" allows you to add a single specific 
item to a given menu and associate an integer "ID" with it. When that item is 
selected by the user and your module is active you will receive a notification 
message containing the integer ID that you passed. 

* the library routine "MEDAAddMenu' allows you to pass a complete, 
standard Macintosh menu structure to the Gatekeeper and have all the 
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menu items specified added in one step. This method is convenient since it 
allows you to use existing resource-creation tools to create menus. From the 
module's point of view, it is just as if the whole menu was added to the menu 
bar. Any time any of the given items are hit, the menu ID and item number 
are sent to the module in a notification message. 


Note: Neither of the above methods necessarily create a new item or menu. 
When the GateKeeper receives a menu add request is scans the existing 
menus to look for a match. If a menu already exists with the given title then the 
existing menu is used rather than creating a new one. This menu is then 
searched for an item with the given text. If such an item exists, then the 
requesting module is associated with the found item, rather than adding a 
second item with the same text. In this way, multiple modules can share 
standard menu items like Cut, Copy, Paste, etc. if the user selects a shared item 
that the active module has linked to, then the active module is notified. It is 
possible for a module to specify that its menu item should be hilited even when 
it is not the active module. 


Code Segments 


: Iti-s en 


In order to handle a range of module sizes, the GateKeeper supports two 
different kinds of module structures, which roughly correspond to the Desk 
Accessory/Driver and Application structures in general Mac programming. In 
general, which type is used will not affect the module code itself, it only affects 
the way the module is compiled and linked. 


Single-Segment (Driver) Modules - In this format all the code for the module is 
placed into a single code resource of type DRVR and uses an interface similar 
to the Macintosh Desk Accessory or Driver. This type of module loads more 
quickly at run time and is somewhat more efficient because it does not use a 
jump table to access internal subroutines. This type of module is limited to 
about 32K in size. MEDA simulation models that are to stored in a library must 
be of this type. 


Multi-segment (Application) Modules - in this format, the module code is broken 
into an arbitrary number of code segments which are loaded independently. 
Jumps between the segments are done via a jump table which is set up when 
the module is loaded. This type of module loads more slowly at run time, but 
the module can be of unlimited size. 


Module Addresses 


Whenever a message is passed between two modules, the GateKeeper fills in 
the addresses of the source and destination modules. From the module's point 
of view, this address should be considered to be nothing more than a unique 
identifier for the module. There is no module-accessible information at the 
given address and the meaning and format of the information may change in 
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future releases of MEDA. 


If the destination address for a message is set to NIL by the originator (the 
normal case), then the GateKeeper locates the appropriate recipient by the first 
letter of the message type and fills in the destination address. 


The destination address will normally only be filled in with a non-NIL value if the 
originator has a need to address the message to a specific module. This may 
come up in the foliowing cases: 


¢ the destination module is a client that requested notification on some event. 
¢ the destination module does not implement any message type, but needs 
to be activated. in this case the originator can look up the module's address 
by name. This might be done to allow a module to implement a button or 
menu command that activates another module. 

* the destination module was loaded by the originator after run time. This is 
used, for example, to load simulation model code from a device library. In 
this case, the GateKeeper returns the destination module's address when 
the module is loaded. 


The "Hello World" Module 


The only thing that is absolutely required of a module is that it respond correctly 
to the "Im" notification message, which is the first message it will receive on 
startup. The response to this message tells the GateKeeper that the module 
was loaded correctly and found the memory and resources it needs and also 
specifies certain operation parameters. After the module has responded to the 
"im", all other messages can be safely ignored and it will still be considered to 
be a valid part of the system. 


The simplest possible module therefore looks like this in C: 


#include “MEDADefs.h" 
#include “MEDAInit.h" 


Boolean gOKToRun; 


/* “Initemds” processes incoming Init notifications */ 


void InitCmds(pTInitMsg pMsq) 


{ 
prinitMsg pInitmsg; 


switch (pMsg->header.msgType[1]) { 
case 'm' : /* First initialization */ 


/* “Im" is the very first thing we receive from the 
GateKeeper after the program is started up. */ 


gOKToRun = MEDAInitMessage(({pTInitMsg) pMsg, 
0, /* Message type we accept */ 
0, /* RefCon for future messages */ 


"Hello" P 
true, 
false, 
false, 
false, 
false, 
false); 


/* 
/* 
{* 
/* 


. fr 


/* 
/* 
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Our name */ 

We're ok to run */ 

Don't want a wake-up immediately */ 
We're not invisible */ 

We don't need idle messages */ 

We don't need access to resources */ 
we don't want System 7.0 events */ 


if (gOKToRun) /* If we are compatible */ 
{ 


/* Send message to debug window */ 


DBOutStr( "Hello world!:",“"); 


break; 
default: 
break; 
} 
} 
/*---------- e+ - +--+ + - + 5 5 5 ee ee nee =f 


/* “MessageReceive" is the entry point for calls from the GateKeeper. 
A pointer to the message record is the only argument */ 


pascal void MessageReceive(pIMsgHeader pMsg)} 


/* Go to appropriate message handling routine base on first char 


/* Init messages */ 


InitCmds((pTInitMsg) pMsg); 


{ 
of message type */ 
switch (pMsg->msgType([0}) 
{ 
case 'I' ;: 
break; 
default: 
break; 
} 
} 


The "MEDAInitMessage" procedure checks the version number in the "Im" 
message to determine whether the version of the interface libraries that the 
module was created with is compatible with the current GateKeeper. If this fails, 
or if the fifth argument ("ok to run") is FALSE, then the GateKeeper does not 


install the module. 
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Initialization and task Management 


The library MEDA\Init contains a set of procedures and notifications for module 
management functions, including: 


¢ loading, unloading and locating a module 
« initialization 
* suspend, resume, wakeup and quit management 


One procedure of special importance is "MEDAInitMessage". This procedure is 
exceptional in that it does not actually send a message but merely fills in the 
fields in the "Im" initialization notification message sent by the GateKeeper. 


Library Routines 


See Library: MEDALRit 


Notifications 


The MEDAInit notifications are provided to manage module functions such as 
initialization, background processing and shutting down. In general, the only 
message that must be acted on is the "Im" (Initialization) which requires that 
certain parameters be set before returning. All others can be ignored as 
needed, although most cannot be masked out,with the exception of "li" (Idle) 
and "Ih" (High level event). 


ee a ey ee ee 
Ie - Exit 


No parameters 


This message is sent to ail modules just before the module is unloaded, i.e. 
after a Quit from the user, a quit request from another module, or a module 
unload operation. This is the last thing the module will ever hear so it should 
use the opportunity to get its affairs in order and deallocate any resources it has 
used. See also the "Iq" notification below, and the "MEDAQuit" library routine in 
MEDAInit. 


Ih - High Level Event 


-> ihEvent Ptr is a pointer to the event record obtained from the 
EventManager. 
<- handled Boolean should be set by the module if it handles the high jevel 


event. If this is not done, the GateKeeper will pass the 
same event on to other modules on the list that 
requested notification. 
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This message is sent to all awake modules that set the "wantHighLevel" flag 
during the "Im" notification. It indicates that a System 7.0 "high level event" was 
received by the GateKeeper. The GateKeeper does not processing on these 
events and assumes that the receiving module will handle it. 


a 


Ii - Idle 
-> liTime : long; 


This message is sent to all awake modules (those that have been loaded and 
activated) who returned "imWantldie" TRUE in response to the Im message, 
each time around the event loop. iiTime is the current event time in ticks. 


Im - Initialize Module 


The "Im" message tells the module to initialize itself, check to make sure it is 
compatible with the current interface version, and perform any needed startup 
processing. If any message type is specified in "imMessageType", the module 
should be prepared to receive these messages immediately after returning from 
the "Im". The module can call the reply procedure for any services needed from 
the Gatekeeper (e.g. debug output), although it cannot assume that the other 
modules are ready to receive messages (See note below). 


The "im" message is sent when the module is first loaded and does not 
represent an activity request from the user. Any user-visible activity (such as 
putting up an empty window) should be done only in response to the "Iw" 
(Wake-up) message (“Iw" will be sent in response to a user action, or after 
initialization if "imStartAwake" was set to TRUE). 


IMPORTANT: The module cannot assume that all other modules are ready to 
receive messages at the time the "Im" is received, since they may not have 
received their "Im" yet. The "In" and “lo" messages are provided for cases 
where the module needs to request services (e.g. a notification request) from 
other modules. "In" is sent by the Gatekeeper only after all modules have been 
sent an "Im". 


NOTE: The procedure "MEDAinitMessage” is provided in the MEDAlInit module 
which greatly simplifies the response to this message. 


Parameters: 


-> imMEDAVersion — short is a version number which defines the format of the 
messages described in this document. When a new 
version of the DesignWorks/Gatekeeper package is 
released which would invalidate messages expected by 
older modules, this number will be incremented. The 
module should check this number and return FALSE in 
“imOKToRun if the value is not what it expected. 

<- imOKToRun Boolean should be returned TRUE if the module finds the 
resources it needs to continue. !t may want to return 


<- 


<- 


<- 


<- 


imMessageType char 


imStartAwake Boolean 


imUserinvisible Boolean 


imWantidle Boolean 


imNeedResources Boolean 


imWantHighLevel Boolean 


imRefCon Ptr 


imAlias tRefStr 


No parameters 
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FALSE if imMEDAVersion does not match what it is : 
expecting, or if it cannot allocate enough memory, open 
a file it needs, or whatever. If the module returns FALSE, 
it should also set an internal flag to ignore all subsequent 
messages from the GateKeeper. 

is the first letter of a message type that will be accepted 
by this module, or a nuit character if none are accepted. 
should be set to TRUE if module wants to be awake 
immediately upon program startup. This should normally 
be FALSE unless the module implements a function that 
the user would expect to see active as soon as the 
program starts. If this is set to TRUE, the Gatekeeper will _ 
send an lw message immediately after the im and In. 
should be set to TRUE if the module has no directly user 
accessible functions. This will be true for modules that 
implement only simulation models, modules that only 
provide services to other modules, or modules that 
provide some background function and have no user- 
accessible options. When this flag is set to TRUE the 
module will not appear in the Module menu. 

should be set to TRUE if the module wants to receive || 
messages. This incurs significant overhead and should 
only be done if the module needs to do background = 
processing. 

should be set to TRUE if the module needs to have 

access to its resources after initialization. {f this is 

FALSE, the Gatekeeper may close the file. = 
should be set to TRUE if the module wants to receive a 

pointer to any Macintosh high level (System 7) event 

received. 

is a reference contstant that will be returned to the 

module in the "dstRefCon" field of all subsequent 

messages. 

is a character string of up to 16 characters which 

identifies the module for internal purposes. This name is 

for internal use only to allow modules to locate other 

modules by name. This name should not be specified in 

a resource so that it remains constant regardless of 7 
language translations, etc. It never appears to the user. 


es ee ee 
In =- Initialization Part II ss 


This message indicates that ali modules have been sent the "Im" message and 
it is now safe to send messages requiring another module (e.g. notify requests). 


Note that no attempt is made to provide an interlock in cases where a module 
has to contact a second module before it can accept messages from outside. 


Io = Initialization Part III 


No parameters 


This message indicates that all modules have been sent the "In" message. 
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Iq - Quit 


<- iqOKToQuit Boolean ' Indicates that module can quit, i.e. it has no unsaved data 
in its own data structures. If the module sets this to 
FALSE, the Quit operation will be aborted. 


This message indicates that the user has selected the Quit command from the 
file menu, or a quit request from another module. Note that this does not 
guarantee that the program will actually terminate, since some other module 
may say that it cannot quit. The module should wait for the "ie" message before 
deallocating anything it needs to run. 


See also the “le” notification and the MEDAQuit procedure in the MEDAinit 
library. 
ee ee 


Ir - Resume 
No parameters 


This message indicates that the program has received a "resume" event, i.e. it 
was just made active under MultiFinder. 


a 
Is - Suspend 


No parameters 


This message indicates that the program has received a "suspend" event, i.e. it 
was just deactivated under MultiFinder. 





Iw - Wake up 


This message tells the module to start performing its user-visible function. The 
"Iw" message is sent under to following circumstances: 


* by the GateKeeper immediately after "Im" and "In" if the "imStartAwake' 
parameter was returned TRUE from the "Im" message. 

* by the GateKeeper when the user has selected the module from the 
Module menu. 

* by any other module that desires to invoke this one's function in a user- 
visible way. See the MEDAInit library routine "MEDAWakeUpModule’. 


Parameters: 


-> iwNew Boolean is TRUE if the module should invoke a new instance of 
itself (i.e, open a new window in addition to any already 
open) or FALSE to simply select an existing one (using 
the SelectWindow WindowManager cail). If the module is 
not capable of supporting multiple open windows it 
should simply select its window regardless of this setting. 

-> iwObject Ptr is the address of an object for the module to open, or NIL 
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to create an empty window. This will normally be NIL 
when this message is received from the GateKeeper. 
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Window Management _ 


Library Routines 


Lil :_MEDAWindo 


Notifications 


As described in the earlier section on window handiing, most MEDAWindows 
notifications correspond to Macintosh events and are sent to the owner of the 
active (topmost) window. 


p ) to all Notificat 


The following parameters are available in all window notifications and will not 
be mentioned in the individual messages, below: 


-> wAddr Ptr Pointer to the window specified in the event 
-> weEvent Ptr Pointer to the Macintosh event (some messages may be 
internally generated, so this may be NIL) 


W+ - Window Activate 


Indicates that an activate event has been received for a window owned by the 
moduie. 


W- - Window Deactivate 


Indicates that a deactivate event has been received for a window owned by the 
module. 


We - Window Close 


Indicates that the user has clicked in the "go away" box in the given window. 
The module should perform standard Macintosh user-interface processing, 
such as asking if changes should be saved, etc. The Gatekeeper does nothing 
other than send this message in response to a click in the "go away" box; the 
actual closing of the window is completely under the control of the module. 


Wd - Window Drag 


-> wdPt Point Current mouse position in global coords 
-> wdTime long Current event time 
-> wdModifiers short Event modifiers field 
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This message is sent to the owner of the frontmost window each time a null 
event is received from the Macintosh system. 


Wi - Window Idle 


Sent once each time around the event loop regardiess of the cursor position. 
This is intended for use primarily for flashing insertion points and other window 
actions that require continuous updates. 





Wk - Key Pressed 


-> wkChar char; The ASCIil for the key pressed 
-> wkModifiers short; The event modifiers 
<- wkHandled Boolean; Set TRUE if the module handles it 


This message is sent to the module who owns the frontmost window each time 

a key is pressed at the keyboard. The module should set the "wkHandled" field 

to TRUE if it has performed some action in response to the keystroke. if this is 

set to FALSE, the Gatekeeper will check to see if the keystroke could have been 

a menu equivalent. - 


Wp - Mouse Pressed 


-> wdPt Point Current mouse position in global coords 
-> wdTime long Current event time 
-> wdModifiers short Event modifiers field 


This is sent in response to a mouse down event. 


Wr - Mouse Released 


-> wdPt Point Current mouse position in globai coords 
-> wdTime long Current event time : 
-> wdModifiers short Event modifiers field 


This is sent in response to a mouse up event. 


Ws - Window Scroll or Control Hit 


-> wsCont Ptr a handle to the control in question 
-> wsPart short the integer number of the control part in question 
-> wsVert Boolean is a boolean which is TRUE if the control in question was 
the vertical scroll bar for this window. 2 
-> wsHitPoint Point is the point (in control coordinates) where the mouse was 


clicked in the control, 


This message is sent to the module for any control hit in the given window. The 
timing of this message depends on the type of contro! part, as follows: 


* if a mouse click occurs in the "thumb" of a scroll bar, the Ws message is 
sent immediately on the mouse down event and it is the module's 
responsibility to track the subsequent user actions. 
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* if a mouse click occurs in the up or down arrows, or page up or down areas 
of a scroll bar, then a Ws message is sent immediately on the mouse down 
event, then a repeat message is sent each time around the event loop until 
the mouse button is released. The module should thus perform one scroll 
step for each message. 

* if a mouse click occurs in any other type of control, then a single Ws 
message is sent when the mouse button is released in the control. 


The following additional processing is performed when the mouse down first 
occurs, before the first Ws message is sent: 


¢ Set port, clipping and origin for entire window 
¢ Cail FindControl to determine if a control hit 
* If so, call HiliteControi to hilight the item 


The following additional processing is performed before the last Ws message is 
sent: 


* Call HiliteControl to de-hilight the item 


Wu - Window Update 


-> wuRect Rect rectangle to update. This is the bounding rectangle of 
the update region for the window, in global coordinates. 
-> wuAborted Boolean is a boolean which is TRUE if the contro! in question was 


the vertical scroll bar for this window. 


This message is sent in response to an update event. Mac Toolbox routine 
BeginUpdate has already been cailed and EndUpdate will be called after the 
return from this message. If wuAborted is set to TRUE by the module, then 
invaiRect is called on the update rectangle after EndUpdate. This is done to 
allow long redraws to be interrupted by the user to scroll, change scale, etc. 


LL eT 


Wz - Window Resized 


This message is sent to the module if the window has been resized, either by 
the resize box or the zoom box. Any actual updating of the screen should be 
done only in response to a Wu message. The purpose of this message is to 
allow the module to recalculate its screen rectangles, scroll bar positions, scroll 
bar hilighting, or other variables that may depend on window size. 
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Debug /O Facilities . 


Debug window 


The routines in the library “"“MEDADebug' are provided to facilitate debugging of 
MEDA modules. Most of the routines output data in various formats to a "debug 
window" which can optionally be displayed on the screen. The following 
features are implemented to control output to the debug window: 


Eunction Action 


Display debug window Type Cmd-8 

Hide debug window Click in "go-away" box 
Pause debug output Control-S 

Restart debug output Control-Q 


Even with the debug window hidden, there is still a substantial overhead in 
setting up the "MEDADebug" calls, so it is recommended that debug messages 
be removed from your module, or at least commented out, when not needed. 


Library Routines 
Library: MEDADebygd 
Notifications 


None 
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Menu Management 
Library Routines 


ary: AMe 


Notifications 


Mb - Menu Before 
No parameters. 
This message is sent to all awake modules after a click occurs in the menu bar 


but before the menu is pulled down. This is the last opportunity for the module 
to change the status of any menu item before it is displayed. 





Mm - Menu Hit 


This message is sent to the module when a menu item attached to this module 
has been selected. 


Parameters: 


<- mmMenu short is the resource ID of the menu that was hit. If the menu 
was added using the "MA" message, then this will be the 
ID of the module's source menu, not the actual menu. 

<- mmitem short is the item number of the menu item that was hit. If the 
menu was created by the module and added using the 
MP message, then this will be the standard menu item 
number, starting from 1 for the topmost item. If the menu 
was added using the MA message, then this will be the 
menu item number as counted in the module's source 
menu, starting from 1 for the topmost item. If the item 
was added using the Mi message, then the item number 
will be the one assigned by the module in the Ml 
message. 


if the item was set up using the MI message, the module will not have 
knowledge of the menu resource ID for the menu the item was attached to. The 
module must assign a unique item number for each item and ignore the 
mmMenu parameter. 
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ccessing Circuit Information 


Circuit Structure 


Before using any of the circuit access routines, a basic understanding of the 
internal structure of a DesignWorks circuit is necessary. 


Circuit El 


A circuit is represented in memory as a series of linked records of various types. 
In general, the record types correspond fairly directly to the objects you see on 
the screen, the major ones being: 


Function Type Pointer Description 
Identifler Identifier 
Circuit tCircuit pTCircuit Contains information about an open circuit file, 


including pointers to ail the other object lists, open 
page information, etc. 


Device tDevice pTDevice Contains information about each device symbol in the 
diagram, @.g. position, orientation, type (i.e. pointer to 
a “type” record, see below), and pointers to attached 
signals. 


Signal tSignal pTSignal Contains information about one “graphical net", i.e. 
one set of contiguous lines on the screen. Each 
“tSignal" record actually represents one “sub-signal”, 
as described below. One or more tSignal records are 
linked together to from a complete fogical net. This 
record structure is aiso used for busses. 


Pin tDevPin pTDevPin Contains information about a logical “device pin", i.e. a 
connection between a signa! and a device. Each 
tDevPin record contains a pointer to a device, a logical 
(internal, integer) pin number and a visible 
(alphanumeric) pin number. Each tSignal record points 
to a list of these. 


Line tLine pTLine Contains information about a single straight line 
segment. Each tSignal record points to a list of these. 

Text tText pT Text Contains a description of a text item. 

Picture tPict pTPict Contains a description of a graphics item (i.e. a 
miscellaneous picture, not a device symbol) 

Type tType pttype Contains information about a device type, i.e. the 


library definition of a device), including the number of 
pins, default attributes, symbol, internal circuit 
information, and the name, function, position and 
direction of each pin. 


All fields in these records are reserved for internal use and they should be 
modified or accessed only by using the appropriate MEDACircuit library routine. 
The size and fayout of fields is likely to change in future versions of 
DesignWorks as new features are added, so accessing them directly will 
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guarantee to incompatibility of your modules with future versions. In addition, 
none of these records can ever be allocated or disposed by the caller as this 
would fatally confuse the DesignWorks memory allocation scheme. 


For purposes of discussion, we will use the following simple circuit: 


ul 





Note that the signal "A" connects by name from U3-6 to U1-1, and the signal "X" 
connects through the bus named "BUS1". 


This circuit generates an internal structure like the following: 











tCircuit 









TYPE LIST 





BUS LIST SIGNAL LIST DEVICE LIST 


{Signal 
name="A" 

























tSignal 
name="BUS1" 








tDevPin 
pinNum=2 
visPin="6" 


tDevice 
name="U1" 


tDevPin 
pinNum=1 
visPin="1" 











tDevice 
name="U2" 





tDevPin 
pinNum=1 
visPin="3" 


tDevPin 
pinNum=2 
visPin="2" 










tSignal 
name="B" 








tDevice 
name="U3" 


tDevPin 
pinNum=1 
visPin="5" 










tDevPin 
pinNum=2 
visPin="4" 






Each "tDevice" record also contains an array of pointers to the attached signals, 
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but for clarity these are not shown in the diagram. 


Circuit 


The circuit record contains pointers to all the other objects in the circuit, as seen 
above, plus information about pages, size and position of open windows, etc. 
Almost all of the routines to access objects in a circuit will require a circuit 
pointer as an argument. Such a pointer is returned by any routine that creates 
or opens a circuit (e.g. MEDANewCircuit) or can be obtained by calling 
"“MEDAGetCctSelectinfo" which returns a pointer to the current circuit. 


Signals 
For the purposes of this discussion the term "sub-signal" refers to a one 
complete set of contiguous lines, i.e. all line segments touching. Each "sub- 


signal" occupies one “tSignal" record and has an independent ability to be 
named, copied, pasted, etc. 


The term "signal" refers to a complete logical net, i.e. all points that are 
considered electrically connected. In DesignWorks there is no specific record 
type for a signal. A signal consists or any single, unlinked sub-signal (i.e. no 
connections by name or bus), or any group of linked sub-signals (shown 
horizontally linked in the above diagram). When multiple sub-signals are 
connected together by name or bus, one of these is chosen arbitrarily to be the 
"master" and is linked into the circuit's signal list. All other attached sub-signais 
are linked to that master. The master signal holds data that is common to the 
whole logical net, such as the attributes and simulation value. 


The library procedure MEDAGetNextSignal is used to move down the circuit's 
master signal list. This list is sufficient to get all information about the name, 
attributes, list of attached device pins and simulation value of a signal. If you 
need to access any information about the graphical representation of the signal 
(i.e. line segments, page numbers, selected status, etc.) you must use the 
procedure MEDAGetNextSubSignal to move down the list of sub-signals for 
each master. A simple procedure to access all sub-signais would look like this: 


pTsignal pSignal; 
pTsignal pSubSig; 


/* “pCircuit" points to the circuit in question, and is assumed to be passed in */ 


pSignal = nil; 
while MEDAGetNextSignal(pSignal, pCircuit, TRUE) 
{ 
pSubSig = nil; 
while MEDAGetNextSubSignal(pSubSig, pSignal, -1, FALSE) 


/* In here, “pSubSig” will touch all possible sub-signals in the circuit */ 
} 
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Devices 

Devices are stored internally as a linked list, with all devices in a circuit in a 
single list in random order. The procedure MEDAGetNextDevice can be used 
to move through ail devices on this list sequentially. Certain types of "pseudo- 
devices" in DesignWorks, such as bus breakouts, page connectors, etc., will 
also appear on this list, but can be omitted by specifying an option to 
"MEDAGetNextDevice ". This procedure returns a pointer to a device structure 
which can be passed to "MEDAGetDevinfo" to access the contents of the 
internal fields, or to various other procedures that operate on devices. 


_ Each device is associated with an array of pointers to the attached signals. This 

array is indexed from 1 to the number of pins. This pin number is an integer 

which is used for internal purposes only and is not the same as the "visible pin 

number" that appears on the diagram. Signal pointers appear in this array in 

eg same order that the pins appear when the device type is opened in the 
evEditor. 


Each device points to an associated "type" record which contains information 
common to all devices of that type, such as the number of pins, the simulation 
type, the picture and the internal circuit. Any number of devices can point to the 
same type record. 


Screen Updating 


Many of the routines in the Circuit module affect data that may be displayed in a 
visible circuit window. Such routines take an "update" parameter which 
specifies how the screen update is to be handied. This parameter can be set to 
one of the following values: 


uNONE means that no screen updating is to be done, i.e. the screen will be left in 
its old state, which may be invalid. It is up to the caller to arrange 
appropriate updating at some later time. 


uACCUMULATE means that any area affected by the operation in question will be 
accumulated into the update region of the circuit window and the update 
will be done by the system the next time an update event is fetched. This 
is the ideal method when a number of updates are being done at once 
since it ensures that a given area of the screen is only updated once. 


uIMMEDIATE means that the affected objects are redrawn immediately. This should 
normally only be done when a very small number of items are affected or if 
response time is important (e.g. to update the value of an output device 
on the screen, or to indicate progress of an operation). 


Circuit Routines 
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Notifications 


The Circuit module implements a variety of notification messages to inform a 
client module of the status of objects that may be of interest. For example, if you 
implement a simulation model for a device of a given type, you can request to 
be notified each time an instance of that type is created or destroyed. This 
would allow you to associate your own internal data with each instance. 


The circuit module only ever sends notifications to modules that have requested 
them using the "MEDAAddNotify" call. It is very important that the module delete 
any notify requests it has made once they are no longer required (i.e. especially 
if the module is being unloaded). The Circuit module has no way of knowing 
that a given client module has ceased to exist and will continue to send 
notifications until they are removed. This can result in fatal system errors. 










WARNING #1!!!! 





All DesignWorks data structures are very dynamic and can be allocated and 
deallocated at any time based on user actions and requests from other 
modules. It is your module's responsibility to make sure that it is not attempting 
to access data that does not exist any more. It is important to make use of the 
notification messages (especially “delete") to keep up to date on what data still 
exists. 


WARNING #2!!!! 









If you associate your own data with a device or signal using attributes or the 
“misc data" facility, be aware that this data is copied by DesignWorks in 

response to Cut & Paste commands and is also written to and read from files 
verbatim. If you store pointers or other data that may be dynamic, make sure 
ou update them correctly in response to "delete" or "unpack" notifies. 





Ca - Notification of new object created 


-> cCircuit Ptr Pointer to the circuit containing the object 

-> cObject Ptr A pointer to the object of interest. 

-> cObjType tObjectType The type of object pointed to by “cObject". 

-> objRefCon Ptr The user address that was passed when the notification 


was requested. 
Object types supported: tCCT, tDEV 


This notification message is sent just after a new object of the given type is 
created and initialized. In the case of devices, this message is sent as soon as 
the device record is complete and initialized, but before it is placed in its final 
destination circuit. When it is copied to the destination circuit, an "unpack" notify 
will be sent which will tell you the final address of the device. 


Ce - Notification of structural change 
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-> cCircuit Ptr Pointer to the circuit containing the object 

-> cObject Ptr A pointer to the object of interest. 

-> cObjlype tObjectType . The type of object pointed to by "cObject". 

-> objRefCon Ptr The user address that was passed when the notification 


was requested. 
Object types supported: tCCT 
This notification is sent if any structural change has occurred on the given 
circuit, e.g. a device or signal created or deleted, or any connectivity change. 


Moving device symbols, moving or extending lines, or name changes that do 
not change connectivity are not considered structural changes. 


Cd - Notification of dispose 


-> cCircuit Ptr Pointer to the circuit containing the object 

-> cObject Ptr A pointer to the object of interest. 

-> cObjType tObjectType The type of object pointed to by "cObject*. 

-> objRefCon Ptr The user address that was passed when the notification 


was requested. 
Object types supported: tCCTtDEV,tSIG 


This notification is given just before the given object is destroyed. After this 
notification has been received its address should not be used in any other 
MEDACircuit cail. : 


IMPORTANT: In the interest of efficiency, a device or signal delete notify is given 
only if the individual object is deleted, leaving the rest of the circuit intact. 


Ce - Notification of environment change 


-> cCircuit Ptr Pointer to the circuit containing the object 

-> cObject Ptr A pointer to the object of interest. 

-> cObjType tObjectType The type of object pointed to by “cObject". 

-> objRefCon Ptr The user address that was passed when the notification 


was requested. 
Object types supported: tDEV 


The "Ce" notification indicates that some device parameter has changed, such 
as its name, attributes, schematic position, etc. 


NOTE: In DesignWorks 2.5.3 this notification is only given for device name 
changes. Other changes are not detected. 


CL - Notification of Set Params 


-> cCircuit Ptr Pointer to the circuit containing the object 
-> cObject Ptr A pointer to the object of interest. 
-> cObjType tObjectType The type of object pointed to by “cObject". 
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-> objRefCon Ptr The user address that was passed when the notification 
was requested. 


Object types supported: tDEV 


The "Ci" notification indicates that the user has just selected the "Set Params" 
command for the specified object. If a module has requested this notification, 
the Circuit module wil! send the "Ci" message instead of putting up a standard 
Set Params dialog box. This allows the module to implement its own parameter 
dialog that replaces the system one. 


Cj - Notification of join 


-> cCircuit Ptr Pointer to the circuit containing the object 

-> cObject Ptr A pointer to the object that will be expanded. 

-> cObjType tObjectType ‘The type of object pointed to by "cObject". 

-> cxMaster Ptr A pointer to the object being merged (depending on the 


join type, this object may be deailocated). 

-> cxMasterType tObjectType ‘The type of object pointed to by “cxMaster" 

-> objRefCon Ptr The user address that was passed when the notification 
was requested. 


Object types supported: tSIG 
The "Cj" notification indicates that the given two signals have been merged. 


Cl = Notification of close 


-> cCircuit Ptr Pointer to the circuit containing the object 

-> cObject Ptr A pointer to the object of interest. 

-> cObjType tObjectType ‘The type of object pointed to by “cObject”. 

-> objRefCon Ptr The user address that was passed when the notification 
was requested. 

<- cxDirty Boolean Returned by client if it has object data that was changed. 


Object types supported: tCCT 


Co - Notification of Open Internals. 


-> cCircuit Ptr Pointer to the circuit containing the object 

-> cObject Ptr A pointer to the object of interest. 

-> cObjType tObjectType The type of object pointed to by "cObject”. 

-> objRefCon Ptr The user address that was passed when the notification 


was requested. 
Object types supported: tDEV 


The "Co" notification indicates that the user has just selected the "Edit Internais" 
command for the specified object. If a module has requested this notification, 
the Circuit module will enable this menu item when the device is selected and 
send the "Co" message when the user selects the menu command. This allows 
the module to implement its own window to show the internal state of an object. 
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Cp - Notification of pack 


-> cCircuit Ptr Pointer to the circuit containing the object 

-> cObjType tObjectType - The type of object pointed to by "cObject". 

-> objRefCon Ptr The user address that was passed when the notification 
was requested. 

<- cObject Ptr A pointer to the object of interest. 

<- cxinfo long Returned by client 

<- cxSize long Returned by client 


Object types supported: tCCT, tBLOCK, tDEV 


The pack notification indicates that the object in question is about to be written 
to a file or stored in a temporary circuit such as the clipboard. In other words, 
this is the last chance for the module to set up any attributes or a "misc data’ 
block to store module-specific data with the object before it is written out into a 
static format. Note that this does not mean that the object is being disposed of, 
so the module should not do anything that would change the function of the 
object. 


See additional comments below under the "Cu" message. 


Cs - Notification of select 


-> cCircuit Ptr Pointer to the circuit containing the object 

-> cObject Ptr A pointer to the object of interest. 

-> cObjType tObjectType The type of object pointed to by “cObject". 

-> objRefCon Ptr The user address that was passed when the notification 


was requested. 
Object types supported: tPAGE, tCCT 
This notification indicates that a different circuit window has been selected by 
the user or that the selected status of one or more objects in the window has 
been changed. 


Cu - Notification of unpack 


-> cCircuit Ptr Pointer to the circuit containing the object 

-> cObjType tObjectType The type of object pointed to by "cObject". 

-> objRefCon Ptr The user address that was passed when the notification 
was requested. 

-> cObject Ptr A pointer to the block read 

<- cxMaster Ptr Signature of desired block 

<- cxMasterType tObjectType Must be tBLOCK for block unpacks 

-> cxinfo long Signature actually read 

-> cxsize long Size of block read 


Object types supported: tCCT,tBLOCK, tDEV 


This message indicates that the given object has just been "unpacked" from 
some storage format. This is sent whenever objects are read from a file or 
copied from the clipboard (or a similar temporary circuit). This is similar to "Ca" 
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in that the record in memory for the object has just been newly created, but it is 
different in that the record has been filled by the system with existing data that 
was stored from a previous circuit. E.g. if your module had attached a "misc 
data" block to a device and then that circuit was saved in a file, the "mise data” 
block will be read from the file and attached to the device by the system when 
the device record is recreated. Thus it is not necessary for your module to 
allocate another biock. This message is intended primarily for cases where the 
module needs to associate some internal data with a device instance. 


Devices 
A "Cu" notify is sent for every requested device under the following 
circumstances: 


¢ after the entire circuit structure has been read from a file. 
* after each device has been copied from the clipboard into a destination circuit. 


Cirouil 
A "Cu" message is sent for requested circuits after the complete circuit structure 
has been read from a file. 


Eile Block Mechanism 
To be added. 
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Writing Simulation Models Using MEDA 


introduction 


The MEDA interface allows new simulation models to be added to the 
DesignWorks simulator, or models for the existing primitive types to be 
overridden. The MEDA module in effect becomes a subroutine which is called 
each time the input state of a device changes. However, due to the nature of 
the MEDA interface, it is not necessary to modify the main program or perform 
any difficult linking operations. The module is written in a standard 
programming language and can make use of any necessary system facilities to 
produce the desired results (inciuding accessing external hardware!). There 
are no hard restrictions on the timing or the nature of signal changes that the 
module can generate on simulated output pins. 


Overview of DesignWorks Simulator Operation 


DesignWorks performs an event-driven simulation of the signal changes in a 
logic circuit, meaning that device outputs are re-evaluated only when an input 
signal changes state, rather than at every possible time step. Each time a 
signal change event occurs, a list is made of all the devices whose inputs are 
affected by that event. Any other events occurring at the same time are similarly 
evaluated, and affected devices added to the list. A type-specific routine (which 
may be in a MEDA module) is then called for each device on the change list in 
order to determine what output changes are going to occur. These changes are 
added to the event list, their time of occurrence depending upon the device 
delay. No computation is performed for times when no event occurs, so that 
device delay settings and clock values have no effect on how fast the simulation 
is performed. 


The built-in DesignWorks primitive evaluation routines perform a simplified 
digital simulation. They do not take into account factors such as fan-out (i.e. the 
number of inputs connected to a given output), line length (capacitance), 
asymmetrical output drive, etc., except in as much as these affect delay time. 
There is nothing preventing a MEDA simulation module from taking any desired 
factors into account in evaluating the device outputs. 


Time vatues are stored internally using 32-bit integers, but integer overflow is 
avoided by detecting when time is approaching a maximum value (currently 
100,000) and then resetting all time values relative to zero. It is convenient to 
think of the time values as being in nanoseconds, but the interpretation is left to 
the user. 
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For any primitive device with a delay characteristic the delay value is stored in a 
16-bit integer can be set to any integer between 0 and 32767 using. the 
standard primitive dialog box. The delay is used only by the simulation routine, 
so the module is free to attach its own interpretation to this value. The zero 
value is a special case and should only be used with an understanding of how 
the simulation is performed, as described above. In particular, note that on a 
given pass through the simulation routine all the events on the list which occur 
at the current time are scanned and then the new outputs for all affected devices 
are calculated. If any of these devices has a zero delay setting then this will 
result in more changes being placed on the event list at the current time. 
However all these changes emerging from zero-delay devices will not be 
evaluated until the next pass through the simulator. This is done to allow for 
user interaction with the simulation. 


If a zero-delay feedback loop exists in a circuit, the signal changes will be 
simulated and any probes on the diagram will be updated at each pass through 
the simulator. However the events at the head of the list will always have the 
same time value associated with them and the simulated time will never 
advance. This will resuit in the timing window updating stopping until some 
delay is inserted in the loop. Also note that the Pause control will appear not to 
work since it does not actually disable the simulator but only prevents it from 
advancing to events at a time later than the current one. 


Overview of Module Operation 


Types of Modeis 


The current MEDA simulator interface supports two types of models: 


* Library models - these are the most common type. A library model is 
associated with a specific device type and is stored in a library in a similar 
manner to a macro internal circuit. A library model must be a single-code- 
segment (driver) type module and cannot access any resources. (This is 
because there is nowhere in the library format to store them.) NOTE: In 
order to get around the resource restriction, you can split a model into two 
parts, one of which is stored with the device symbol in the library and the 
other is a regular, external MEDA module. The external one can then 
handle any user interaction, or other tasks that require resources. See the 
model example included with the kit for details. 


¢ Primitive models - these are used to replace the internal simulation model 
for one of the DesignWorks primitives, or to create a new primitive type. The 
primitive model is stored in a separate file and is loaded at run time like 
other types of MEDA modules. For this reason it can be a single- or multiple- 
code-segment module and can have any desired resources associated with 
it. Any library device having the given primitive type will invoke a single 
primitive model. 


See information below on using the DevEditor module to create library entries 
for either of these model types. 
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lnitializati 


When the module is first loaded (at run time for a primitive model, or when the 
type is used for a library model), the Gatekeeper first sends an initialization 
message "Im" to the module allowing it to perform general startup 
housekeeping. The module then calls the simulator requesting notification on 
signal changes affecting the given type. It can also request to be notified when 
any device of that type is created, modified, or deleted, allowing it to attach its 
own data to the device. 


Simulati 


The device in question is read from a library by the user and used in a 
schematic just like any other DesignWorks device. Whenever an input value to 
the device changes, a notification message is sent to the module allowing it to 
compute new output values, as needed (see notifications below). The module 
can send messages back to the simulator to request that simulation events be 
scheduled for a future time based on the device's characteristics. Other than 
the resource restriction noted for library models above, simulation models are 
just like any other MEDA module and can make us of any window, menu, debug 
or other facilities and can perform any hardware access or I/O needed. 


Simulation Data Types 
The following data types are relevant to simulation operation: 


Time 


All time values are specified as a 32-bit signed integer. The negative values 
are not defined. Al! module-visible time values are relative to the current time. 
I.e. If the module requests an event to be scheduled at time 10, this will occur 10 
units in the future. 


Signal values 


Signal values are stored in a byte, allowing potentially 256 values. In the 
normal simulation, only the 13 states discussed in the DesignWorks manual are 
implemented. These are specified using an enumerated type, as follows: 


LOW 
HIGH 
DONTO1 
HIGHZ 
CONF 
DONTOZ 
DONT1Z 
LOWL 
HIGHL 
DONTOiL 
CONFL 
DONTOZL 
DONT1ZL 


— —- —s 
NY-$-QOWVANGDUBRWNH-O 
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There is currently no provision for implementing new signal values (in addition 
to the existing 13), although this may be done in the future. 


Primitive 3 


The primitive type is a byte value in the type description record that selects 
which simulation routine will be used to simulate the device, as weil as being 
used to mark special schematic pseudo-devices, such as bus breakouts and 
page connectors. The primitive type "MACRO" indicates a device that has a 
functional internal circuit. An external MEDA model can replace the internal 
simulation code for any of the existing types shown in the following table, or it 
can be used to implement a new type using a type value which is currently 
unused. Instructions are given below for creating a library device and 
associating it with a given primitive type. 


Mnemonic Type Byte (decimal) 


NOT 0 
AND2 1 
NAND2 2 
OR2 3 
NOR2 4 
XOR2 5 
DFF 6 
JKFF 7 
HEXKEYB 8 
SWITCH 9 
HEXDISP 10 
PROBE 11 
CLOCK 12 
OCBUF 13 
TSBUF 14 
PULLUPA 15 
NAND3 16 
NAND4 17 
NAND8 18 
AND3 19 
AND4 20 
NOR3 21 
NOR4 22 
PULLUPB 23 
OCNAND, 24 
COUNTER 25 
SHIFTREG 26 
8TO1MUX 27 
3TO8DEC 28 
TSBUF4 29 
ONESHOT 30 
SPST 31 
REG8 32 
ADDER4 33 
RES 34 
OR3 35 


OR4 36 
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PROM 37 
PLA 38 
Reserved 39 
RAM 40 
Reserved 41 
Reserved 42 
SPDT 43 
Reserved 44 
XGATE 45 
Reserved 46 
Reserved 47 
Reserved 48 
Reserved 49 
Reserved 50 
Reserved 51 
Reserved 52 
BUFFER 53 
DFFNi 54 
JKFFNI 55 
XNOR2 56 
ANDS5 57 
NANDS5 58 
ORS 59 
NORS5 60 
Reserved 61 


Reserved 62-127 


Writing the Simulation Module 


Module Initialization 
The sequence of events for initializing a simulation module are as follows: 


* module is loaded, global data is allocated, Modula-2 initializion code (the 
main code section of each module) is executed. No messages can be sent 
in initialization code. 

« module receives "Im" initialization message. Module should do any initial 
setting of variables or general housekeeping, but no user-visible action. 
Messages can be sent to the Gatekeeper at this time for debugging 
messages, creating windows, etc. but messages cannot be sent to other 
modules (e.g. MEDACircuit or MEDASimulate routines) since they may not 
be initialized yet. 

¢ module receives the "In" initialization message, meaning that all modules 
have now been initialized and are ready to receive messages. Module can 
call the following routines to set up notification requests: 


* MEDAAddSimNotify is used to request notification each time a device 
input changes, or other simulation cases listed below. 

* MEDAAddCirNotify to the drawing module, requesting notification 
whenever a device of the given type is created, deleted, or parameters 
modified. This allows the module to allocate private state data for each 
instance of the device. 
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Instance Creation 

Instances of the new primitive type are created by the user in DesignWorks just 
like any other device: loading it from a library and placing it on the schematic, 
or using the Cut/Copy/Paste/Duplicate editing commands. It the module 
requested create/delete notification at startup, using the "MEDAAddCirNotify " 
routine, it will receive an "Cx" message each time a device of the given primitive 
type is created or deleted ('x" being replaced by the appropriate letter). it can 
then use the attribute routines to create or access attribute fields, or the 
"MiscData" routines to create a binary data block in the device record. This 
allows the module to allocate a block of memory to contain private state data for 
the device. 


Setting Parameters 
NOT IMPLEMENTED YET! 
Simulation C 


When the state of any input to a device of the specified primitive type changes, 
the simulator will send the module an "Sp" message if requested. This 
message passes the following useful information to the module: 


* field “spPinList" points to an array of pointers to the signals attached to the 
device. This can be used to access the values on these signals and to set 
up new output change events. 

* field "spPinNum" passes the pin number that was used in a "device event’, 
i.e. an event that specified a device but no specific signal. This will normally 
be zero. 

¢ field "spMiscData" passes a pointer to the device's "misc data" biock. This 
block can be allocated and deallocated by the module to hold any desired 
data. 


The module can then use the following routines (among others) to get or set any 
desired values: 


* "MEDAGetSignalRange" and "MEDAGetSignaiNewValue" to ascertain the 
current signal values. 
¢ "MEDASetUpPinEvent'" to schedule signal change events on the outputs. 


Creating a Device Type in a Library 
In order to associate a device type in a library with the simulation model code 
the following procedures must be followed in the DevEditor module. 


odels 


The following description assumes you understand normal DesignWorks and 
DevEditor operation: 
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1) Select the DevEditor module in the Module menu. 

2) Create a new symbol or open an existing symbol. 

3) Place the pins on the symbol. NOTE: Order is very important. The first pin 
in the list is Pin 1 to the simulator, the next is Pin 2, etc. When accessing the 
pin signal array from within the model, the first entry is the signal on Pin 1, 
etc. 

4) Select the Set Primitive Type command in the DevEditor menu. A 
scrolling list of primitive types will appear. 

5) Double-click on the "Behavioural..." entry in the type list. A standard file 
box will appear. 

6) Select the file of tyoe "MEDA" containing the model code. 

7) Click on the first pin in the pin list and click on the “Set Info" button. 

8) Set the pin type to "input" or "output" in turn, clicking the "Next" button to 
proceed to the next pin. The simulator will complain loudly if you attempt to 
schedule a signal change event on an input pin. The DevEditor does not 
allow pin type to be set for macros (the defauit primitive type), so this step 
must be performed after setting the primitive type. 


NOTE: It is convenient to create the symbol before creating the model code so 
you can make use of the "Copy Pin Names" command in the DevEditor menu to 
create a pin definition list. This saves typing a lot of "#define" or similar 
statements in yourself. 

Primitive Model 

TO BE ADDED! 


Simulation Library Routines 


Simu 


Simulation Messages 


Sc - Notification of Clear Timing 


-> sCircuit Ptr Pointer to the circuit containing the object 

-> sObjType tObjectType Must betCCT 

-> objRefCon Ptr The user address that was passed when the notification 
was requested. 

-> sObject Ptr Circuit pointer 

-> sTime long Current time 


Object types supported: tCCT 
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Sp - Notification of device input change 


-> sCircuit Ptr Pointer to the circuit containing the object 

-> sObjType tObjectType . Must be tDEVICE 

-> objRefCon Ptr The user address that was passed when the notification 
was requested. 

-> sObject Ptr Device pointer 

-> sTime long Current time 

-> spPinNum short For device events: Pin number specified in event 
For signal events: 0 

-> spPinList Ptr Pointer to device pin signal list 

-> spMiscData Ptr Pointer to device misc data biock 


Object types supported: tDEVICE 


Sq - Notification of simulator queue empty 


This notification indicates that the simulator has completed processing for the 
current time step and there are no events on the queue. This means that the 
circuit is now in a stable state and could be checked for results of some 
stimulus. 


-> sCircuit Ptr Pointer to the circuit containing the object 

-> sObjType tObjectType Must betCCT 

-> objRefCon Ptr The user address that was passed when the notification 
was requested. 

-> sObject Ptr Circuit pointer 

-> sTime long Current time 


Object types supported: tCCT 


Ss - Notification of end of time step 


This notification indicates that the simulator has finished all processing for this 
time step and is about to calculate the next time value. This is the last chance to 
set up events relative to the current time. 


-> sCircuit Ptr Pointer to the circuit containing the object 

-> sObjType tObjectType Must betCCT 

-> objRefCon Ptr The user address that was passed when the notification 
was requested. 

-> sObject Ptr Circuit pointer 

-> sTime long Current time 


Object types supported: tCCT 
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St - Notification of any signal change 


This notification indicates that any signal that had a value change notification 
request on it changed during the processing of this time step. 


-> sCircuit Ptr Pointer to the circuit containing the object 

-> sObjType tObjectType Must betTIME 

-> objRefCon Ptr The user address that was passed when the notification 
was requested. 

-> sObject Ptr Current time value 

-> sTime long Current time 


Object types supported: tTIME 
Su - Notification of Clear Unknowns 


This notification indicates that the simulator is about to perform a Clear 
Unknowns operation on the given circuit. 


-> sCircuit Pir Pointer to the circuit containing the object 

-> sObjType tObjectType Must betCCT 

-> objRefCon Ptr The user address that was passed when the notification 
was requested. 

-> sObject Ptr Circuit pointer 

-> sTime long Current time 


Object types supported: tCCT 


Sv - Notification of signal value change 


-> sCircuit Ptr Pointer to the circuit containing the object 

-> sObjType tObjectType Must be tS!IG 

-> objRefCon Ptr Tne user address that was passed when the notification 
was requested. 

-> sObject Ptr A pointer to the block read 

-> sTime long Current time 

-> svNewVal tSigVal New signal value 

-> svOldVal tSigVal Old signal value (before change at this step) 


Object types supported: tSIGNAL 
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Sw - Notification of time wraparound 


This notification indicates that the simulator is about to reset time values back to 
zero. The value in "sTime" will be subtracted from all time values in the system. 


-> sCircuit Ptr Pointer to the circuit containing the object 

-> sObjType tObjectType Must betCCT 

-> objRefCon Ptr The user address that was passed when the notification 
was requested. 

-> sObject Ptr Circuit pointer 

-> sTime long Current time 


Object types supported: tCCT 
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Appendix A - The MEDACircuit Library 


/* Tab test: 
x x x x x x x x 
x x x x x x x x 
«/ 





- a ee ea ee en oe ee oe eee 


"MEDACircuitAvailable" determines whether the circuit module 
is available, i.e. whether any of the othar calle in this 
library will succeed. Since the user can configure a system 
without the circuit module, it is important to make this call 
before assuming that any of the other “MEDACircuit" calls 
will work. If this returns FALSE, and you need other calls 
to proceed it is up to you to put up an appropriate error 
bax and bail out gracefully. 





RETURN VALUE TRUE if MEDACircuit is available, 
FALSE otherwise. 


PARAMETERS 


none 
Woe ee a wo = = = a ee rrr ee wee eee re ee a 
+/ 

PQUALIFIER Boolean MEDACircuitAvailabie(); 





“MEDAAddCctNotify” sets up a request to be notified when some 
event occurs in the circuit. Read the printed documentation 
in the MEDA Reference Manual before attempting to use this 


routine. 
* 
RETURN VALUE none 
* 
PARAMETERS 
. 2 
object Pointer to the object you wish to be notified 
about, or NULL to be notified about any 
object of the given type. 
objType The type of object you wieh to be notified about. 
refCon A reference constant that will be returned 
to you in any notification message that results 
fram this request. This can be a pointer to 
your internal data, or any other value that 
is convenient. It has no significance to the 
system. 
mask This is a character string which lists the types 
of notifications (the second letter of the 
Message type) you wish to receive. An empty 
string will pass all message types. 
¥ ewe ee eee ee eee eee we ewe ee eee eee == ale i ap ap ae ome oD Oo ee a a - es ae owe 
*/ 
PQUALIFIER void MEDAAddCctNotify( Ptr object, 
tObjectType objType, 
Ptr refCon, 


char *mask }; 





“MEDADelCctNotify“ cancels an existing notification request. 
Read the printed documentation in the MEDA Reference Manual 
before attempting to use this routine. 


* 
RETURN VALUE none 
* 
PARAMETERS 
* 
object Pointer to the object exactly as passed to 
the original MEDAAddCctNotify call. 
ebjTypa The type of object exactly as passed to 
the original MEDAAddCctNotify call. 
refCon A reference constant exactly as passed to 
the original MEDAAddCctNotify call, exept 
that passing a value of NULL causes the first 
notify having the given object pointer to 
be removed, without checking “refCon“. 
femewewnnnanwewsecennnenn=: we nemnn anna new en ene nen en nnn sonnanesaee Seereeerre senna nee- 
«/ 
PQUALIFIER void MEDADelCctNotify({ Ptr object, 
tObjectType ob Type, 
Ptr rerCon )}; 
ftiotacticlosscacaneess! SSeecees=eS ew eee solSoS tewsene teweatacoe ee ye 
Circuit File Operations 
Tene ow ow oe ae er ee eee ee ==: ee a a A eeeeeenee: onan ww ewer ese= 
*/ 
[feonnnnn- ene ------- 20 ---- === eteseeecane anne eS Soleeeoe pe aee ate ‘ancn aia wanewonay 
"MEDANewCircuit” creates a new circuit etructure in memory. 
If “visible” is TRUE, then the new circuit is set to be the current one. 
. 7 
RETURN VALUE pointer to the new circuit, or NULL if there was 
any error, 
+ 
PARAMETERS 
* 
visible TRUE if the new circuit's window should be displayed. 
tone eww eee eee = ib ab G0en an anenan anew ar an ar: oe SS A AD aD OD OD OE ars eel pee on mae ee ee ee: Oe a ees woe 
«/ 


PQUALIPIER piCircuit MEDANewCircuit( Boolean visible ); 





* "MEDAOperNamedCircuit” reads a circuit file from disk and creates 4 new 
circuit structure in memory. 


RETURN VALUE Pointer to the new circuit, or NULL if there was 
any error. 
. 
PARAMETERS 
* 
fileName Text name of file to open. If this is an empty 
string, then the user will be prompted with 
a standard file box. 
wdRef Working directory ID of file to open. This is ignored 
if the fileName is empty. 
visible TRUE if the new circuits windows should be displayed. 
¥ eee ee ee = = oe ee a a oa ew a a a a a a a a ee a ee 
+f 
PQUALIFIER pTCircuit MEDAOpenNamedCircuit( char *fileName, 
short wiRef, 


Boolean visible ); 
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“MEDAOpenMamoryCircuit” reads a circuit file from the given mamory block 
and creates a new circuit structure in memory. 


RETURN VALUE pointer to the new circuit, or NULL if there was 
any error. 
PARAMETERS 
handle Memory handle of the block to read. 
visible TRUE if the new circuits windows should be displayed. 
aad 22s ee a ee ee A ee a ae Sl eshstententententententenienl 
/ 
PQUALIPIER pICircuit MEDAOpenMemoryCircuit( Handle handle, 
char *cotNane, 
Boolean visible ); 





"MEDACLoseCircuit” closes the given circuit. 


RETURN VALUE none 

PARAMETERS 

peircuit Pointer to circuit to close, or NULL for current one. 
ee nn Resta cate a eae Breet 
PQUALIFIEZR void MEDACloseCircuit( pTCircuit pecircuit }; 





*MEDASaveCircuit” saves the given circuit to the file it was 
read from. If this circuit was not read from a file and has 
never been saved, this will have no effect. 


RETURN VALUE none 

PARAMETERS 

pcircuit Pointer to circuit to save, or NULL for current one. 
Ci ag TR ee, eee paea eget 
PQUALIFIER void MEDASaveCircuit ( pTCireuit pcireuit ); 





“MEDASaveCircuitAs” writes a circuit file to disk. 


RETURN VALUE Error number, or 0 if OK 
PARAMETERS 
. 
pcireuit Pointer to circuit to save, or NULL for current one. 
fileName Text name of file to open. If thie is an empty 


string, then the user will be prompted with 
a standard file box. 


wdRef Working directory ID of file to open. This is ignored 
if the fileName is empty. 
writeHeader TRUE (normal setting) to write a 


complete circuit header in the file. 
If this is set to FALSE the circuit will 
open with default windows and print info. 


Kwon meee ne eee eee eee we a a nn ns a eee 


*/ 
PQUALIFIER short MEDASaveCircuitAs ( piCircuit pCircuit, 
char *fileName, 
short wdRef, 


Boolean writeHeader ); 


“MEDASaveMemoryCircuit® writes a circuit file to a memory block. 


* 
RETURN VALUE Error number, or 0 if OK 
* : 
PARAMETERS 
* 
pCircuit Pointer to circuit to save 
handle A handle already created before the call. 
The size will be adjusted as needed. 
writeHeader TRUE (normal setting) to write a 
Complete circuit header in the file. 
If thie is set to FALSE the circuit will 
open with default windows and print info. 
Pee ee ew wo ee oe ern ne nn 2 re eee eee eee eee ee te Ct ad 
*/ 
PQUALIFIER short MEDASaveMemoryCircuit( pICircuit pcircuit, 
Handle handle, 
Boolean writeHeader }; 
/*---------- we emo m meen ena wane wn meee eee ere we tee en none enon ereee one eee enna — 
Circuit Drawing Operations 
We ew eee ee oe ow oe ee a re 2 ne ee ee eee ee ee ee eee eee = neee ee eee Oe 
«/ 
Dt ee ee oo Sew ene ween enn e = == o-------- ween----= 
“MEDANormalSize" performs the equivalent of the "Normal Size” menu 
command on the given circuit page. If the page is not open, or if it 
is already normal size, nothing is done. 
J 
RETURN VALUE none 
* 
PARAMETERS 
* 
pcircuit Pointer to circuit to change 
page Page number to change 
tawoeenesoceeseeeoseeseeeseee crn owe we els i i id ie at a eh oa Rae ee eee o—— 
*/ 
PQUALIFIER void MEDANormaiSize({ pICircuit pCircuit, 
short page ); 
{ tenon ene we owe === = = = = == = -- = == - == ree oe a pc co a a a a me a - a 
“MEDAEnlarge” performs the equivalent of the “Enlarge” menu 
command on the given circuit page. If the page is not open, or if it 
is already enlarged to ite maximum extent, nothing is done. 
* 
RETURN VALUE nona 
* 
PARAMETERS 
* 
pcireuit Pointer to circuit to change 
page Page number to change 
pees ih al te caw i ta i on i ta gi a owl) 5 nS sot eaeennnenn 
*/ 


PQUALIFIER void MEDAEnlarge{ pTCircuit pCircuit, 


short page ); 
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"MEDAReduce” performs the equivalent of the “Reduce” menu 
command on the given circuit page. If the page is not open, or if it 
is already reduced to its maximum extent, nothing ia done. 


RETURN VALUE none 
* 
PARAMETERS 
* 
pcireuit Pointer to circuit to reduce 
page Page number to reduce 


* wo een an == oe ne a Se a SSR eS ee 


/ 


PQUALIPIER void MEDAReduce( pICircuit pcircuit, 
short page }; 





“MEDAReaduceToPit" performs the equivalent of the “Reduce To Fit" menu 
command on the given circuit page. If the page is not open, or if it 
iu already reduced to its maximum extent, nothing is done. 


RETURN VALUE none 
* 
PARAMETERS. 
* 
pCircuit Pointer to circuit to reduce 
page Page number to reduce 
aa One ea See Fay peraceaNs Bra eects 
PQUALIFIER void MEDAReduceToFit( pTCircuit pcireuit, 


ehort page ); 





"MEDAGOToSelected” causes the selected items on the 
given page to be centered in the visible portion of 
their window. No change is made to the window's 
“open” or "active" status. If no items are selected 
nothing is done, 


RETURN VALUE none 

° 
PARAMETERS 

4 
pcircuit Pointer to circuit to operate on 
page Page number to operate on 

Pe em eee ee ee en ee eee en ewe oe = ee ee we en er aan enna 

/ 

PQUALIFIER void MEDAGoToSelected( pICircuit peircuit, 


short page ); 





“MEDADisplaySelected” causes the selected iteme on the 
given page to be centered in the visible portion of 
their window, unless they are already completely 
visible, in which case nothing is done. This is similar 
to "MEDAGOToSelected” except that nothing is done if the 
items are already visibie. If no items are selected 
nothing ie done. 


RETURN VALUE none 
* 
PARAMETERS 
¥ 
pCircuit Pointer to circuit to operate on 
page Page number to operate on 


fee wen ee re oe ew ee ee ee eee ee ee eee n= ee ee ee ee ee eee ee eee sees ~~ 


*/ 
PQUALIFIER void MEDADisplaySelected( piCircuit pCircuit, 
short page ); 
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"MEDAGoToRect” is similar to "MEDAGoToSelected” except that 
it adjusts the given window to center the given rectangle 
(in circuit coordinates) rather than the selected items 


on the page. 


RETURN VALUE none 


PARAMETERS 
* 
pcireuit Pointer to circuit to operate on 
page Page number to operate on 
rect Rectangle to center in window. This is 
given in circuit coordinates (i.e. 
1/2000") 
wee ne eee eee Ree we enn ee See eee eR ase ete A ee 
*/ 
PQUALIFIER void MEDAGoToRect( piCircuit pCircuit, 
short page, 
Rect rect }; 

[Beeman ewe nnn ne 2 ow on nn eno nn nn ne nena nana aman eanneene we eewe nnn 
“MEDAOpenCctPage” opens a new window or displays the existing window for 
the given circuit page. “behind” is a pointer to the window behind which 
the cizcuit page window should be positioned, or -] to appear at the 
front, or 0 to appear at the back, as described in the “NewWindow" call 
in the Mac Window Managez. . 

4 
RETURN VALUE none 
* 
PARAMETERS 
* 
PCircuit Pointer to circuit to operate on 
page Page number to operate on 
behind Window to open behind 
® ewer en eee ie 00 a ae om ee os i ep at d sa seal anees ts wl on eae we eee eee wow + me ne eonaee em 
«/ 

PQUALIFIER void MEDAOpenCetPage( pICircuit pCircuit, 

short page, 
WindowPtr behind }); 





"MEDASetCctPagePort” sets the window for the given circuit and page 
to be the current GrafPort. If the given page is not open, then 
FALSE is returned and the GrafPort ia not changed. 


RETURN VALUE TRUE if the given circuit page is open in a window, 
FALSE otherwise 


PARAMETERS 
* 
pcircuit Pointer to circuit to operate on 
page Page number to operate on 
Vemeesennenn nnn weennnnnee wmnneene n= Licenaonam ein ii omnes oe ewww ene wen a=== eon 
*/ 
PQUALIFIER Boolean MEDASetCctPagePort ( pTcircuit pCircuit, 


short page }; 





*MEDAUpdateCctPagePalatte” redraws the tool palette in the given 
circuit page window. If the window ie not open, nothing is done. 
This will normally be called by an external simulator to change 
the similation control portion of the palette. 


RETURN VALUE none 
* 

PARAMETERS 
* 

pCircuit Pointer to circuit to operate on 

page Page number to operate on. 

0 = current, -1 = all, >0 specific page 

Veen ccewn anaes aneer=--=--=- ia ty i i ei cpaaaacow peaereceya eeneoeeeeeeeenes 
7d 
PQUALIPIER void MEDAUpdateCctPagePalette({ pTCircuit pCircuit, 


short page ); 





“MEDAGetScreenRect" converts the given rectangle in circuit coordinates 
into a rectangle in local coordinates of the window for the given 
circuit and page. If the given circuit page is not open in a window 
the resulta are undefined. 


RETURN VALUE none 
* 
PARAMETERS 
* 
pCircuit Pointer to circuit to operate on 
page Page number to operate on 
rect Rectangle to convert 
Wenwenannn awn eee enn nn anne nn ee enewnnnne canoe ee ene oe ene anne eee o+----=-- 
*/ 
PQUALIFIER void MEDAGetScreenRect( pICircuit pcircuit, 


short page, 
/*VAR*/ Rect *rect ); 





"MEDADrawDevice” drawa the given device in its window. 


RETURN VALUE none 
* 
PARAMETERS 
* 
pcircuit Pointer to circuit containing the device 
pDavice Pointer to the device to draw 
update uIMMEDIATE means draw the object immediately. 


UACCUMULATE means that the area covered by 
the abject will be added to the update region 
and redrawn by the next update event. 
uNONE does nothing. 
0 eee ee ee ee ee oe eee ee = =: oo ee a ee ee 
*/ 
PQUALIFIER void MEDADrawDevice({ piCircuit pcircuit, 
pTDevice pDevice, 
tUpdateLevel update ); 
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“MEDADrawSubSignal“ draws the given sub-signal in its window. 


RETURN VALUE none 
* 
PARAMETERS 
* 
pcircuit Pointer to circuit containing the sub-signal 
pSignal Pointer to the sub-signal to draw 
update uIMMEDIATE means draw the object immediately. 


UACCUMULATE means that the area covered by 

the object will be added to the update region 

and redrawn by the next update event. 

uNONE does nothing. 

Werner n—-- ae weoe-- semen n= === 2 oe on = === eonenccn meen cacenme eine la eee 
*/ 
PQUALIPIER void MEDADrawSubSignai( pICircuit pCircuit, 

pTSignal pSignal, 
tUpdatelevel update ); 


[Waone--- neon nano 2 nee ----- 2 oon === === iin iis tn, ee ae ancien 





tales eee eee eee = eee A a ee ee 


“MEDADrawCircuit” draws the given circuit page in its window. 


RETURN VALUE none 
* 
PARAMETERS 
* 
pcircuit Pointer to circuit containing the signal 
page Page number in the given circuit 
update uIMMEDIATE means draw the page immediately. 


uACCUMULATE means that the page 

will be added to the update region 
and redrawn by the next update event. 
UNONE does nothing. 


«/ 

PQUALIFIER void MEDADrawCircuit( pICircuit pCircuit, 
short pageNun, 
tUpdateLevel update ); 





“MEDAInstallType” installs the given type record in the syetem's list of 
known device types. Note that this call is different from the 
“MEDAAdGXxx" calls in that it doesn't create a new object ina circuit, 
it merely installs the given one in a global list of types that are 
available for device creation. This mat be called before a type 

can be used in MEDAAddDevice. 


If this type already exists in the system then a handle to the existing 
type record is returned, otherwise it returne the handle it is given. 


RETURN VALUE Handle to the type record that will actually be used. 

If this type did not already exist in the system, 
then this will be the same as the argument passed. 
If the type did already exist in any open circuit, 
then a handle to the existing type is returned and 
the new one is not installed. It is the caller’s 
responsibility to dispose of the unused one. 


PARAMETERS 

* 
pecircuit Pointer to circuit to associate type with 
type Handle to the type record to install 


Rawemmn en eww noe eee ewan eee see eee =: ae me eee eee eee eee 
*/ 
PQUALIFIER pIType MEDAInstalifype( piCircuit pCircuit, 

priype type )7 
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“MEDAAdGDevice” creates a new device instance on the given circuit and page- 


RETURN VALUE Pointer to device created, or NULL if there was any error 


* 
PARAMETERS 

* 
peircuit Pointer to circuit to place the new device in 
page Page number to place new device on 
davicelype Handle to device type for new device. 


Note that this type must have been installed 
using “MEDAInstallType” before it can be used to 
create deviogs in a circuit. 
position Position on diagram in 1/1000". 0,0 is at 
the center of the diagram in a new circuit 
orientation One of the 8 possible orientations 
hitCheck TRUE to test for connections of the signals 
to existing ones on the diagram 
update Screen update action 


«/ 

PQUALIFIER pTDevice MEDAAddDevice( pTCircuit circuit, 
short page, 
pItype deviceType, 
Point position, 
tPinDir orientation, 
Boolean hitCheck, 
tUpdateLevel update ); 





“MEDAChangeDevType” changes the type of the given device to the one given. 

The new type must match the old one in primitive type and number, direction 
and relative position of pins. The symbol iteelf can change as long as the 
relative positions of the pins are the same. The stored position of the 

top left corner of the device is offset automatically to keep the pin positions 
constant. 


If the device is a macro, the old internal circuit is deleted and a new one 
ereated according to the circuit block in the new type record. 


IMPORTANT: The type passed in “newIype” must have been intalied previously 
using “MEDAInatallType” before passing it ae an argument here. 


RETURN VALUE TRUE if the type was converted successfully, FALSE if there 
was an incompatibility in primitive type or pin placement. 


PARAMETERS 
* 
pCircuit Pointer to the circuit containing the device 
to be changed 
pDevice Pointer to the device to change 
newTypa Handle to the type record to use as the new device type 
update Type of screen update to perform in case symbol 
changed. 
| sip sto li eae tap Suess aanawne ae oe ne we wae eeeoneae: op en on ee PD 
*/ 
PQUALIFIER Boolean MEDAChangeDevType( pICircuit pCircuit, 
prDevice pDevice, 
pitype newType, 


tUpdateLevel update }; 





RETURN VALUE None 
7 
PARAMETERS 
* 
pcircuit Pointer to circuit containing the device 
pbevicea Pointer to the device to delete 
update Screen update action 
tocccdsawsenanaccasecmeaancnnancoscensncocccse= sipudeswaaeesccusss St otecounoe esncee 
*/ 
PQUALIFIER MEDADeleteDevice( pICircuit pCircuit, 
pIDevice pDevice, 
tUpdatelLevel update ); 





"MEDAAGdSignal” creates a new signal on the given circuit and page. 
* The new signal will initially be invisible (since it has no associated 
* lines) and have no destination pins. Same associated lines or device 
* pins should be added immediately following thie call. 
* If it is left in this form the DesignWorks “bug sniffer" will 
* issue an error message to the user. 
* 


RETURN VALUE: None 


PARAMETERS 
* 
peireuit Pointer to circuit to contain the new signal 
page Page number to contain the new signal 
cc i cabs men ca eae enh easel ee inns malin a alae at eee ee Sees ebes 
*/ 
PQUALIFIER pTSignal MEDAAddSignal( pICircuit pCircuit, 


short page ); 





“MEDADeleteSignal“ deletes the given signal from the circuit. 
Any lines associated with the signal are deleted. If the signal 
had any device pin connections, new signal records are created 
for each associated device pin. 


RETURN VALUE: None 


PARAMETERS 
* 
pcircuit Pointer to circuit to contain the new signal 
pSignal Pointer to signal to deletes 
update Screen update action 
Wa nl he ln SeesecccccosessosS ip einen enamels ie ice ail eae ate 
+f 
PQUALIFIER MEDADeleteSignal{ piCircuit peircuit, 


pTSignal pSignal, 
tUpdateLevel update ); 





"MEDAAGSPin” creates a new pin (i.e. a connection to @ device) on the 


given signal. IMPORTANT: This should only be used for the extremely 
unusual case where an existing device pin has no signal associated 
with it. Normally a device pin is created with an associated signal 
and connections are made using the “Join” operations below. 


RETURN VALUE: Pointer to the pin record, or NULL if any error 
* 
PARAMETERS 
* 
pecircuit Pointer to circuit containing the objects 
pSignal Pointer to the signal to add the pin to 
pbevice Pointer to device whose pin is being added 
pinNum Logic pin number on device 
visPin Visible pin number character etring 
fe ee ee eee ee eee er ee oo A ee ween = —— 
*/ 
PQUALIPIER pTDevPin MEDAAddPin( pICircuit pcircuit, 
pTSignal pSignal, 
pIDevice pDbevice, 
tPinNizn pinNum, 
tVisPin visPin ); 





"MEDAAdGLine” 


RETURN VALUE: 


creates a new graphical line associated with the 
given sub-signal. 


Pointer to the line record, or NULL if any error 


PARAMETERS 
x 
pcircuit Pointer to circuit containing the objects 
pSignal Pointer to the sub-signal to add the lina to 
endA, endB Endpoints of the line segment, which 
must be vertical or horizontal 
hitCheck TRUE to check endA for a join to another signal 
update Screen update action 
Ceoeenooeee<=: enna aaeresaee st ls De tel ia Siento ke ip aaa wah iad cea aa sae Aa pla i casa ap sims ele ee 
Led 
PQUALIPIER pTLine MEDAAddLine( pTCircuit pcircuit, 
pTSignal pSignal, 
Point endA, 
Point endB, 
Boolean hitCheck, 
tUpdateLevel update}; 


"MEDAAdGDevMiscData” creates a memory block of the given size 
attached to the given device. The block will be uninitialized 
and will be saved with the device in a file and copied during 
clipboard operations. WARNING: A given device can only 

have one of these blocks attached to it. If some other module 
has already attached data, this call will return NULL. 


RETURN VALUE Pointer to data, or NULL if any error 
PARAMETERS 
pcircuit Pointer to circuit containing the device 
pdevice Pointer to device to attach data to 
size Size of block to allocate 
¥ eae - === eewenseren------- oe en en wee nema nn nna nn enn nnn enn en nanan nee ~ee- 
*/ 
PQUALIFIER Ptr MEDAAddDevMiscData{ pICircuit pcircuit, 
pTDevice pbevice, 
long size ); 


“MEDADelDevMiscData” deletes a memory block attached 
to the given device that was created using 





MEDAAddDevMiscData. 

PARAMETERS 

peircuit Pointer to circuit containing the device 
pdevice Pointer to device 


* ewe eee eee Se OE Re Se eee See eee ee ee oe ee ee oe 
«/ 
PQUALIFIER void MEDADelDevMiscData( pItireuit pcircuit, 
pTDevice pDevice ); 


[Wuciniweccecianaoens Scsvesssboeseatoses Seddons tates 


List searching operations 





“MEDAGetNextCircuitType” gets the next device type on the List 
for the given circuit. Note that this returns all types ina given 
hierarchical design, not just those used in the given sub-circuit. 


RETURN VALUE: TRUE if a aon-NULL value returned 





PARAMETERS 
* 
pType The address of a type pointer. 
Oa entry: This should contain the last pointer 
returned by MEDAGetNextCircuitType, or NULL to start 
at beginning of list 
peirouit Pointer to circuit containing the devices 
refSort TRUE to sort by reference, i.e. types are guaranteed 
to appear on the list before any other type whose 
internal circuit refers to it. .If thie 1s FALSE, 
types will be returned in random order. 
¥ ween ee eee eee eee: oe oe ae oe a ee oO ae oo an enw pe ae ee a ee A a 
*/ 
PQUALIFIER Boolean MEDAGetNextCircuitType( pTType *pType, 
pItircuit pCircuit, 
Boolean refSort )} 
[teweweanoecewnnern= sens eessone: 
“MEDAGetNextDevice” gets the next device on the list for the given circuit. 
* 
RETURN VALUE: TRUE if a non-NULL value returned 
* 
PARAMETERS 
* 
pDevice The address of a device pointer. 
On entry: This should contain the last pointer 
returned by MEDAGetNextDevice, or NULL to start 
at beginning of list 
pcircuit Pointer to circuit containing the devices 
pageNum Page number to find devices for. 0 means current 
page, -1 means all pages, >0 means page number 
visible TRUE to list only visible devices, i.e. those 
not inaide macro devices 
selected TRUE to list only devices currently selected 
(hilited) on the diagzam. 
inelPseudoDevs TRUE to list pseudo-devices (such as page connectors, 
bus breakouts, etc) otherwise these are omitted. 
Tannen = we eee eee ee oe ee we ew ee ee ee ess 
«/ 
PQUALIFIER Boolean MEDAGetNextDevice( /*VAR*/ piDevice *pDevice, 
prcircuit pCircuit, 
short pageNum, 
iean visible, 
Boolean selected, 


Boclean inc]lPseudoDevs }; 
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MEDAGetNextSignal” geta the next signal on the list for the given circuit. 
This does not return pointers to buases. NOTE: This routine does not allow 
selection by page number or selected status (as in MEDAGetNextDevice) because 
a signal can exiet across mitiple pages and each sub-signal can have 
different selected status. You mat use MEDAGetNextSubSignal 

to move within a sub-signal list to select the ones that match your criteria 
* 


RETURN VALUE: TRUE if a non-NULL value returned 


PARAMETERS 
° 
pSignal The address of a signal pointer. 
On entry: This should contain the last pointer 
returnad by MEDAGetNextDevica, or NULL to start 
at baginning of list 
pcircuit Pointer to circuit containing the signals 
visible TRUE to list only visible signals, i.e. those 
not inside macro devices 
Ceween mone wooo eee wee eee eee ewer = wow OO eum meme mew: ce a i es ia \a0 6p qos en man apenas: sto 2p an a ewan aw ae 
*/ 
PQUALIFIER Boolean MEDAGetNextSignal( /*VAR*/ pTSignal ‘*pSignal, 
picircuit pcircuit, 
Boolean visible ); 





MEDAGetNextBus” gets the next bus on the list for the given circuit. 


RETURN VALUE: TRUE if a non-NULL value returned 


PARAMETERS 
* 
bus The address of a bus pointer. 
On entry: This should contain the last pointer 
Teturned by MEDAGetNextDevica, or NULL to start 
at beginning of list 
pcircuit Pointer to circuit containing the signals 
visible TRUE to list only visible busses, i.e. those 
not inside macro devices 
tena annem wwe see eee ee eee ewe wee eee > ah ap an ap aman om a a a ae a ina gh ih ass deemed vate wa at oa saa mae nee eee we 
*/ 
PQUALIFIER Boolean MEDAGetNextBus( /*VAR*/ pTSignal *bus, 
pICircuit pcireuit, 
Boolean visible ); 
[Pacccesncescastanan Be he eck Ss lees memo cces ees c ce cSso ees 
"MEDAGetNextSubSignal” gets the next sub-signal on the list 
for the given signal. 
. 
RETURN VALUE: TRUE if a non-NULL value returned 
* 
PARAMETERS 
* 
pSubSig The address of a bus pointer. 
On entry: This should contain the last pointer 
returned by MEDAGetNextSubSignal, or NULL to start 
at beginning of list. 
pSignal Pointer to the master signal 
pageNum Page number to find devices for. 0 means current 
page, -1 meane all pages, >0 means page number 
selected TRUE to list only sub-signals currently selected 
(hilited) on the diagram. 
twee ne eee ee eee ewer een aeneersersr= bE A wee ewe ewww ee eee 
*/ 
POQUALIFIER Boolean MEDAGetNextSubSignal( /*VAR*/ pTSignal *pSubSig, 
pTSignal pSignal, 
short pageNum, 


Boolean selected }; 
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“MEDAGetNextBusSignal" gets the next signal on the list 
for the given bus. 


RETURN VALUE: TRUE if a non-NULL value returned 


* 
PARAMETERS 
* 
pSignal The address of a signal pointer. 
On entry: This should contain the last pointer 
returned by MEDAGetNextBusSignal, or NULL to start 
at beginning of list. 
bus Pointer to the bus in question 
# mecenn-=seeeeee=--=-= Aeacennennamame ee LsSecoeoc ase: aencee -------- saennnene ween ----= 
*/ 
PQUALIFIER Boolean MEDAGetNextBusSignal( /*VAR*/ pTSignal *busSig, 
pTSignal bus }; 





"MEDAGetNextPin” gets the next pin on the list 
for the given signal. 


. 2 
RETURN VALUE: TRUE if a non-NULL value returned 
. 
PARAMETERS 
* 
pin The addresa of a pin pointer. 
On entry: This should contain the last pointer 
returned by MEDAGetNextPin, or NULL to start 
at beginning of list. 
pSignal Pointer to the signal in question 
subonly If TRUE, only pins on the given sub-signal 
will be returned, otherwise all pins 
logically connected to the same master 
will be returned. 
Raw eeaeewowe=— we cena anaoee are Ona eae wae ww: clean iene sein rl ay mi ED aD OED ED" si tn ett ee Ty 
/ 
PQUALIFIER Boolean MEDAGetNextPin( /*VAR*/ pTDevPin *pin, 
pTSignal pSignal, 
Boolean subOnly); 
| re iene cin aanincwowoamaesed: Vecewan pees eeneme wen 
“MEDAGetNextLine“ gete the next line on the list 
for the given sub-signal. 
* 
RETURN VALUE: TRUE if a non-NULL value returned 
* 
PARAMETERS 
* 
line The address of a line pointer. 
On entry: This should contain the last pointer 
returned by MEDAGetNextLine, or NULL to start 
at beginning of list. 
pSignal Pointer to the signal in question 
tetera 0 ee ee a a om ee ee a  o tated a a a eee a - 
*f 
PQUALIFIER Boolean MEDAGetNextLine( /*VAR*/ pTLine *line, 


pTsignal pSignal, 
Boolean nonPin ); 


a7A.8 








"MEDAGet Next Text" returns a pointer to the next text item in the 
given circuit's list. 


RETURN VALUE TRUE if a non-NULL value returned. 
PARAMETERS 
plext On entry, this VAR parameter should contain 


the last pointer returned by MEDAGetNextText, 
or NULL to start at the beginning of the list. 
On exist this returns a pointer to the next 
item on the list, or NULL if the end of the 
list has been reached. 











pcircuit The circuit to check for text. 
page The page to check for text. 
selected TRUE to return only pointers to selected text items 
one enn ee oe on $2 one enn enna ck ii init a owen een een 
*/ 
PQUALIFIER Boolean MEDAGetNextText( /*VAR*/ pTText *plext, 
pIcireait pCircuit, 
short pageNun, 
Boolean selected ); 
[¥amewe naan e ae onan een nn === ie hie namie ee aes as het es aso itt a amc ee 
"MEDAGetNextPict” returns a pointer to the next pict item in the 
given circuit's list. 
RETURN VALUE TRUE if a non-NULL value returned. 
PARAMETERS 
pPict On entry, this VAR parameter should contain 
the last pointer returned by MEDAGetNextPict, 
or NULL to start at the beginning of the list. 
On exist this returns a pointer to the next 
item on the list, or NULL if the end of the 
list has been reached. 
pCircuit The circuit to check for pict. 
page The page to check for pict. 
selected TRUE to return only pointers to selected pict items 
* een eee ne eee eee eee ee ee ee nes ee ete nee eter eaeeens eee ‘i ona ates saan erewnwae 
*/ 
PQUALIFIER Boolean MEDAGetNext?ict( /*VAR*/ pIPict “pPict, 
prcircuit pCircuit, 
short pageNum, 
Boolean selected }; 
[ Baewnn ane enn nen nnn 
"MEDAGetNextCct” gets the next currentiy open circuit 
RETURN VALUE: TRUE if a non-NULL value returned 
PARAMETERS 
pCircuit The addresa of a circuit pointer. 
On entry: This should contain the last pointer 
returned by MEDAGetNextCct, or NULL to start 
at beginning of list. 
® awe momen w ene anne oe eee en nnn nnn ee ene ne ane aaaisaeiee mee ee nee ea nne enn e= eonnne----- 
«/ 


PQUALIFIER Boolean MEDAGetNextCct { /*VAR*/ pTCircus *pCircuit ); 


Routines to get and set object characteristics 


9 eee mn eee oe ee ee ee ee ee ee ee = wee en enn eee ee = ~~ ween: 


/ 





"MEDAGetCctInfo" gets information about the given circuit 


RETURN VALUE: None 


PARAMETERS 
peircuit The address of the circuit in question 
parent Returns a pointer to the device containng 
this circuit, or NULL if this is the top 
level in the hierarchy. 
NOTE: This ia supported only in DW 3.0 
and later! 
master Returns a pointer to tha topmost circuit in 
the hierarchy in this design (may point to itself) 
NOTE: This is supported only in DW 3.0 
and later! 
numPages Returns the number of pages in this circuit 
open Returns TRUE if the circuit is open for editing 
(i.e. one or more pages open in windows } 
*/ 
PQUALIFIER void MEDAGetCetInfo( piCircuit pCircuit, 
/*VAR*/ pTDevice “parent, 
/*VAR*/ pICircuit ‘master, 
/*VAR*/ short *numPages, 
/*VAR*/ Boolean *open); 





“MEDACircuitOpen” is a simplified version of "MEDAGetCctinfo” 
which returns only the “open” status of the circuit. 


RETURN VALUE: TRUE if circuit has any pages open for editing 
PARAMETERS 
pecireuit The address of the circuit in question 


ial 
PQUALIFIER Boolean MEDACircuitOpen( pICircuit pCircuit); 


[Wewee san ene nee n nnn noe 2 ono one 





“MBDAGetDeviInfo” gets information about the given device 
RETURN VALUE: None 
PARAMETERS 


pdevice The address of the device in question 
pinList Returns a pointer to an 
array of pointers to signals attached 
to the device's pins 
pType Returns a pointer to the 
device type definition 
position Returne a point giving 
the position of the top left corner 
of the device symbol in 1/1000° 
pageNum Returne the page number of the device 
selected Returns TRUE if the device is currently 
selected (hilited} on the diagram 
invisible Returns TRUE if the device is invisible 
(i.e. inside a macro device) 
omit Returns TRUE if the “Omit from Report” 
awitch is on in the Set Params box 
noWarn Returns TRUE if the “mark as OK” bit 
has been set 
subdev Returns a pointer to the first internal 
device, or NULL if this is not a macro 
NOTE: This will not be supported in DW 3.0! 
token Returne the device's token number 
frame Returns the bounding rectangle in 1/1000" 
parent Returns a pointer to the circuit containng 
this device 
child Returns a pointer to the internal circuit 
if this is a sub-circuit, or NULL otherwise. 
NOTE: This is supported only in DW 3.0 
and later! 


*/ 

PQUALIFIER void MEDAGetDevinfo( pIDevice pDevice, 
/*VAR*/ Ptr ; *pinList, 
/*VAR*/ pType *plype, 
/*VAR*/ Point *position, 
/*VAR*/ short *pageNum, 
/*VAR*/ Boolean *selected, 
/*VAR*/ Boolean *invisible, 
/*VAR*/ Boolean *amnit, 
/*VAR*/ Boolean *noWarn, 
/*VAR*/ pTDevice *subDev, 
/*VAR*/ long *token, 
/*VAR*/ Rect ‘fram, 
/*VAR*/ pTCircuit *parent, 
/*VAR*/ pICircuit *child); 





“MEDAGetDevType” is a simplified version of MEDAGetDevinfo that 
xeturns only the device type pointer. 


RETURN VALUE: Device type pointer 
PARAMETERS 


plevice the address of the device in question 


+f 
PQUALIFIER pIType MEDAGetDevType( pTDevice pDevice ); 


[ton-wneen nnn eenenncenee 





"MEDAGetDevMiscData” returns a pointer to the device's 
mise data block, allocated using "MEDAAddDevMiscData” 


RETURN VALUE: Misc data block pointer 


PARAMETERS 

pDavice The address of the device in question 
*/ 
PQUALIFIER Ptr MEDAGetDevMiscData( pTDevice pDevica }; 





“MEDAGetDevPinSig" returns a pointer to the signal attached 
to the given pin of the given device. If you will need 

to access most of the signals on a device, then it is 

much more efficient to use "MEDAGetDevSigLlist” below. 


RETURN VALUE: Signal pointer 


PARAMETERS 
pbevice The addrese of the device in question 
pin The logical pin number in question 


wee ee eee eRe eee eee ee eee eee ooo 60 60 ae ees ees oe ee oe ee oe one 

*f 

PQUALIFIER pTSignal MEDAGetDevPinsig( pTDevice pDevice, 
tPinNum pin ); 





“MEDAGetDevSigList” returns a pointer to an array of pointers 


to signals. 
RETURN VALUE: Pointer to an array of pointers to signals, as follows: 
Returned addrese-> Pointer to signal for pin 1 
Pointer to signal for pin 2 
coc. 
PARAMETERS 
numPins returns the total number of pina on the device 
(i.e. the number of elements in the eignal array) 
Veen eee eres eee ===: 2 ee ae ee ee eon aamae: 2a ee ee esau oan oan ee ov on oe a a oe oe: -———— 
*/ 
PQUALIFIER Ptr MEDAGetDevSigList( pTDavice pdevice, 


/*VAR*/ tPinNum *numPines ); 


¥ ewe eee a eee ee 2 ee we ee ae 


«} 





"MEDAGetTypeInfo” returns information about a device type 
given a pointer to the type record. 


RETURN VALUE: None 
PARAMETERS 
devType Pointer to the type in question 
primtype Returns the primitive type value 
nmumPins Returns the total number of pins 
maninpe Returns the total number of inputs. 
For macro types, this ie normally equal 
to the number of pins. 
numuts Returns the total number of outpute. 
For macro types, this ie normally set 
to zero. 
delay Returns the default delay for this type 
pict Returns a handle to the iibrary picture 
{i.e. the East-facing one) 
poly Returns a handle to the library poly 
info Returns a handle to the internal info 
block. This will normally only be 
useful for user-defined primitive types 
model Returns a pointer to the behavioural model 
for the given type 
intCetDet Returns a pointer to the internal circuit 
definition, or NULL if none. 
lLibtype Returns a flag indicating wheather this is 
a library type, as cpposed to an on-sheet 
hierarchical block. 
5 ee ee a Sia eid cincait gat ebiipasnat iba ones a ae ee a op nn on ee ne oe 
*/ 
PQUALIFIER void MEDAGetTypeInfo( pIType devType, 
/*VAR*/ tDevTypes *primlype, 
/*VAR*/ tPinNum *numPins, 
/*VAR*/ tPinNum *numInps, 
/*VAR*/ tPinNum *numouts, 
/*VAR*/ long *delay, 
/*VAR*/ PicHandle *pict, 
/*VAR*/ PolyHandle *poly, 
/*VAR*/ Handle *tinfo, 
/*VAR*/ Ptr *model, 
/*VAR*/ pTCircuit *intcetDef, 
/*VAR*/ Boolean *libType ); 





“MEDAGetTypeModel” returna a pointer to the behavioural model 
for the given type, or NULL if none. 


RETURN VALUE: 


PARAMETERS 


devType 


Returns a pointer to the behavioural model 
for the given type, or NULL if none 


Pointer to the type in question 


PQUALIFIER Ptr MEDAGetTypeModel( pTType devType ); 
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“MEDAGet TypePinInfo“ returns information about a device type 
pin given a pointer to the type record and a pin number 


RETURN VALUE: None 


PARAMETERS 
devType Pointer to the type in question 
pinNum The pin number in question 
pinket Returns the pin name 
pindir Returns the pin direction 
pinType Returns the pin type 
devVisPin Returns the default visible pin number 
pinPos Returns the pin position, relative to 
the top left corner of the symbol in 
standard orientation, in 1/1000" 
pinLen Returns the length of the pin, in 
circuit coordinates 
locked Returns the locked status of the pin. 
This will be TRUE if this pin has been 
connected to on any instance of the type 
“OP gnc tek ees ct ee eee en ee ee evn os en a ee eee ee ee eee en es ee oe ee ee en ee ed eeeeenane. ao 
*/ 
PQUALIFIER void MEDAGetTypePinInfo( piType devType, 
tPinNum pinNum, 
/*VAR*/ tRefStr pinkef, 
/*VAR*/ tPinDir *pinDir, 
/*VAR*/ tPinType *pinType, 
/*VAR*/ tVisPin defVisPin, 
7*VAR*/ Point *pinPos, 
/*VAR*/ phort *pinLen, 
/*VAR*/ Boolean *locked ); 





“MEDAGetMasterSigInfo"” returns information ahout a master signal 


RETURN VALUE: None 


PARAMETERS 
pSignal Pointer to the signal in question 
masterBus Returns a pointer to the bus containing 
this signal, or NULL if none 
bue Returns TRUE if this is a bus 
display Returns TRUE if this signal is displayed 
in the timing diagram 
omit Returns TRUE if the “Omit from Report” flag 
has been set for this signal 
tewenecenr= see neeeneeen one wee eees nee en eeee ee weer eere=: ab eS Se OE Oe a a ae 
*/ 
PQUALIFIER void MEDAGatMasterSigInfo( pTSignal pSignal, 


/*VAR*/ pTSignal *masterBus, 
/*VAR*/ Boolean *bus, 
/*VAR*/ Boolean *display, 
/*VAR*/ Boolean ‘amit ); 


-77- 





"MEDAGatSubSiginfo” returns information about a sub-signal 


RETURN VALUE: None 

PARAMETERS 

sig Pointer to the signal in question 

pageNum Returns the page number of this sub-signal 

frame Returns the bounding frame including all 
lines and names 

selected Returns TRUE if this sub-sig is currently 
selected (hilited) on the diagram 

invisible Returns TRUE if this sub-sig is invisible 


(i.e. inside a macro device) 


© aww ne 2 eee oo ee een ee eee ee oo a a a a ene ee ee ewer eee een 


«/ 

PQUALIFIER void MEDAGetSubSigInfo( pTSignal sig, 
/*VAR*/ short *pageNum, 
/*VAR*/ Rect *frane, 
/*VAR*/ Boolean *selected, 
/*VAR*/ Boolean *invisible ); 





“MEDAGetPininfo" returns information about the device pin 
pointed to by “pin”. 


RETURN VALUE: Nons 


PARAMETERS 
pin Pointer to pin record in question 
pdevice Returns a pointer to the device 
pinNum Returns the pin index (1..numPins)} 
visPin Returns the visible pin number string 
pinType Returna the simulation type of the pin 
® wean eee toe tit ED OD OOS OS ON eS ae a ee Smenaaanaa wa eeesanaes aaa aeaeeeres to on eae ee: - 
+/ 
PQUALIFIER void MEDAGetPinInfo( pTDevPin pin, 
/*VAR*/ pTDevice *pDevice, 
/7*VAR*/ tPinNum *pinNum, 
/*VAR*/ tVisPin visPin, 
/*VAR*/ tPinType *pinlype }; 





“MEDASetPiniInfo" sets the visible pin number string 
on the given pin record. 


RETURN VALUE: None 


PARAMETERS 
pcircuit Pointer to circuit containing the objects 
pin Pointer to the pin record to change 
visPin New value for visible pin number 
update Type of acreen update to perform 
ft pe ee ww en eee ee = == a a a a a ee ee a ee a ee ee ae a eS a ae - 
*/ 
PQUALIFIER void MEDASetPinInfo( prcircuit pcircuit, 
prpevPin pin, 
tVisPin visPin, 


tUpdateLevel update }; 


“MEDAGetLineInfo” returns information about the signal line 
pointed to by “line”. 


RETURN VALUE: None 


PARAMETERS 
line Pointer to line record in question 
endA Returns the point at the upper or left 
end of the line, in circuit coordinates 
endB Returns the point at the lower or right 
end of the line, in circuit coordinates 
blobA Raturns TRUE if a blob is drawn at pointA 
blobB Returns TRUE if a blob is drawn at pointB 
pinLine Returne TRUE if this line is a device pin 
Caner ee eee ee === =: 22 eee ee 22 a ee a ee ee eee eee, 2 woo 
e/ 
PQUALIPIER void MEDAGetLinelnto( prLine line, 
/*VAR*/ Point *endA, 
/*VAR*/ Point *andB, 
/*VAR*/ Boolean *blobA, 
/*VAR*/ Boolean *blobB, 
/*VAR*/ Boolean *pinLine ); 
[tenuneoeew==----- soot ip ia sai gitar ca nora 
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"MEDASetDevWarnFlag” sets the “mark as OK" flag in the given device. 


RETURN VALUE: None 


PARAMETERS 
pDevice Pointer to the device in question 
value TRUE to set the flag, FALSE to clear it 
9 ee wee ee ee we eee eee = ween ema oe Panay on eee ae en osee eee oe ae 2 ee oe ee ona 
*/ 
PQUALIFIER void MEDASetDevWarnFlag( pTDevice pdevice, 


Boolean value }; 





“MEDAGetDevWarnFlag" returns the value of the “mark as OK” flag 
in the given cevice. 


RETURN VALUE: Value of “mark as OK” flag 


PARAMETERS 
pDevica Pointer to the device in question 
© eww eee ee ae ee oe ee a ee eee eee === aan ers =< ee eee <== - 
ef 
PQUALIFIER Boolean MEDAGetDevWarnFlag{ pTDevice pdevice ); 





“MEDASetSigWarnFlag” seta the "mark as OX“ flag in the given signal. 


RETURN VALUE: None 
PARAMETERS 
pSignal Pointer to the signal in question 
value TRUE to set the flag, FALSE to clear it 
#2 ese eee ee ee === === eaten somecccese Secosos. <oocee ais re eee, aati aennnn 


«/ 
PQUALIFIER void MEDASetSigWarnFlag( pTSignal pSignal, 
Boolean value }; 





“MEDAGetSigWarnFlag” returns the value of the “mark as OK” flag 
in the given signal. 


RETURN VALUE: Value of “mark as OK” flag 

PARAMETERS 

pSignal Pointer to the signal in question 
¢ ee en en ee ne ee a a ee ee ee eres 


*f 
PQUALIFIER Boolean MEDAGetSigWarnFlag( pTSignal pSignal ); 





Signal connection operations 


Pn ee eon wenn ee == a a a a a a = om ew ewe wenn 


*/ 
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"MEDAJoinSigToSig” logically connecte the two given signals 


RETURN VALUE: TRUE if successful, FALSE if the two signals were 
incompatible, e.g. one was a bus or they were 
both inside busses 


PARAMETERS 


pcireuit Pointer to the circuit containing the signals 

sigi Pointer to the firat signal. This will noxmally 
end up being the resulting master signal unless 
the second signal is in a bus or is being 
displayed in the timing diagram. 

Big2 Pointer to the second signal. If “touch” is TRUE 
this one will normally end up being deallocated. 

touch Set to TRUE to merge the two signals into a single 
sub-signal aa if the two were connected together 
with a line. In this case, one of the signals 
ceases to exist. Set to FALSE to connect logically 
as if they were named the same. In this case, one 
becomes a sub-signal of the other, but both records 
atill exist. Note that no checking is done to make 
eure the names are the sama. Subsequent editing 
by the user may cause connectivity to be re-evaluated 
if the names were not the same. 

flash Set TRUE to flash both signals to indicate a connection 
to the user. 

ees Seen aaa 2 ow a oe ee oe oO - pan ee a e —e eee oe oo 
*/ 

PQUALIFIER Boolean MEDAJoinSigToSig( pICircuit pCircait, 
pTsignal sigl, 
pTSignal B1ig2, 
Boolean touch, 
Boolean flash }; 
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"MEDAJoinSigToDevPin“ is the same as “MEDAJoinSigToSig” except 
that the second signal is specified as a device pointer and 


pin number. 


RETURN VALUE: 


PARAMETERS 


pCircuit 
pSignal 


PDevice 


touch 


«/ 


PQUALIPIER Boolean MEDACoinSigToDevPin{ piCircuit 


TRUE if successful, FALSE if the two signals were 
incompatible, e.g. one waB a bus or they were 
both inside busses 


Pointer to the circuit containing the signals 
Pointer to the first signal. This wili normally 
end up being the resulting master signal unless 
the second signal is in a bus or is being 
displayed in the timing diagram. 

Pointer to the devioe to connect to 

Pin number to connect to on the given device 

Set to TRUE to merge the two signals into a single 
sub-signal as if the two were connected together 
with a line. Set to FALSE to connect logically 

as if they were named the same. 

Set TRUE to flash both signals to indicate a connection 
to the user. 


peircuit, 
pSignal, 
pdevice, 
pinNum, 
touch, 
flaah ); 


pTSignal 
pIDevice 
tPinNum 
Boolean 
Boolean 





“MEDAJoinDevPinToDevPin” is the same as “MEDAJoinSigToSig” except 
that both signals are specified as a device pointer and 
pin number. 


RETURN VALUE: 


TRUE it successful, FALSE if the two signals were 
incompatible, e.g. one was a bus or they were 
both inside busses 


PARAMETERS 

pCircuit Pointer to the circuit containing the signale 

devi Pointer to first device 

pinNuml Pin number on firet device 

dev2 Pointer to the davice to connect to 

panNum2 Pin number to connect to on the second device 

touch Set to TRUE to merge the two aignals into a single 
sub-signal as if the two were connected together 
with a line. Set to FALSE to connect logically 
ag if they were named the same. 

flash Set TRUE to flash both signals to indicate a connection 


Wee oe oe oe eee ee 


TO the user. 


sf 
PQUALIFIER Boolean MEDAJoinDevPinToDevPin( pTCircuit pCircuit, 

prDevice devi, 
tPinNum pinNuml, 
pTDevice dev2, 
tPinNum pinNum2, 
Boolean touch, 
Boolean flash ); 





“MEDAUnjoinDevPinFromSig” isolates the given device pin. If 
it is currently connected to othar device pins, a new signal 
is created and it is moved to the new signal. If the attached 
signal goes to no other pins, then nothing is done. 


RETURN VALUE: TRUE if successful, FALSE if any problem 


PARAMETERS 
peirouit Pointer to the circuit containing the signals 
pDevice Pointer to device 
pinNum Pin number on first device 
sig Returns a pointer to the zesulting signal 
on the given pin 
V en newcen enn enaeenanannnanaenesennn= ea sant einai tar a ancien saose neces weal cnet 
+f 
PQUALIFIER Boolean MEDAUnjoinDevPinFromSig( pTCircuit pCircuit, 
pTDevice pDevice, 
tPinNum pinNum, 


/*VAR*/ pTSignal sig ); 





Name search and set operations 
I sche om ea sg seh ang Sb os pf bs ein pip i pg oii line ee ea a OF io i a io th 
*/ 
ftrtewessaceswees cede Soo cede soeueseaecease= ee a ewcticeusss sasee 
"MEDALCokDevByName" looks for a device of the given name in 
the given circuit. 
RETURN VALUE Pointer to the device of the given name, 
or NULL if no match found 
PARAMETERS 
pcircuit Pointer to the circuit to search. If this 
is NULL, the current circuit is searched. 
page Page number to search. "0” means 
search the current page, “-i" means 
B@arcn all pages. 
fran Pointer tc device after which to start 
gearcnuing. If this is NULL, searching starts 
fram the head of the list. Passing the value 
returned by each call to successive calle 
searches for mltiple instances of the name 
in the list. 
name Device name to locx for. Case is significant. 
Ween wen manmnnnennewenwen ese n ec eee oe en enn connec ewe ens emeneenneee ese s— io pie 
«/ 
PQUALIFIER pTOevice MEDALCoxDevByName( pICircuit pCircuit, 
short page, 
pIDevice from, 
char “name )j 
f Beene nnn ne ee ne ee en en ee oe ee = ee eee eee eeee= <= 
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“MEDALOokDevByToken” looks for a device with the given token in 
the given circuit. 


RETURN VALUE Pointer to the device of the given token, 
or NULL if no match found 
PARAMETERS 
peircuit Pointer to the circuit to search. If this 
is NULL, the current circuit is searched. 
page Page number to search. “0” means 
search the current page, “-i" means 
search all pages. 
token Device token to look for. 
We ee ee ee ee oe we ee oe ee we ee ee re ee eee rr ee eee 
*/ 
PQUALIFIER pTDevice MEDALookDevbyToken{ pTCircuit pCircuit, 


short page, 
long token ); 
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"MEDALOokDevPinByNum" looks for a device pin on the given device 
with the given visible pin number. 


RETURN VALUE Pointer to device pin of the given name, 
or NULL if no match found 





PARAMETERS 
plevice Pointer to the device to search. 
from Pointer to device pin after which to start 
searching. If thie ia NULL, searching starts 
ram the head of tha list. Passing the value 
xeturned by each call to successive calls 
searches for miltiple instances of the number 
in the list. 
pinNum Pin number to look for. Case is significant. 
Peewee ween=n--= i i ei oe a wee nena nn coon on en ne ene enn e === sok i 
/ : 
PQUALIFIER pTDevPin MEDALookDevPinByNum( pTDevice pDevice, 
pTDevPin. from, 
tVisPin pinNum }; 

7 i ea eawane sce eaemameeen soncceemannne Somseteeusos Soe 
“MEDALOokPinSigByName” looka for a davice pin on the given device 
with the given name and returns a pointer to the attached signal. 
RETURN VALUE Pointer to aignal on pin of the given nate, 

or NULL 14 no match found 
PARAMETERS 
poevice Pointer to the device to search. 
fram Pointer to pin signal after which to start 
searching. If this is NULL, searching starts 
from the head of the list. Passing the value 
returned by each call to succeasive calls 
searches for mitiple instances of the nunber 
an the list. 
pinName Pin name to look for. Case ia significant. 
fceenw ew ee ee ene eee en en en ene wee ee eee nnn nen nnne = oa as tah inte ei winner 
*/ 
PQUALIFIER pTSignal MEDALookPinSigByName { piDevica pdevice, 


pTSignal fron, 
tRefStr pinName }; 





“MEDALOokSigByName” looks for a signal of the given name in 
the given circuit. 


RETURN VALUE Pointer to signal of the given name, 
or NULL if no match found 
PARAMETERS 
pcircuit Pointer to the circuit to search. If thia 
is NULL, the current circuit is searched. 
page Page number to search. “0” means 


search the current page, “-i" means 

search all pages. 
fram Pointer to signal after which to start 
searching. If this ia NULL, searching starts 
from the head of the list. Passing the value 
returned by each call to successive calls 
searches for miltiple instances of the name 
in the liet. 
Signal name to look for. Case ie significant. 





«/ 

PQUALIPIER pTSignal MEDALookSigByName ( pTCireuit pcircuit, 
short page, 
pTSignal from, 
char *namea }; 








"MEDALOOkSigByToken" looks for a signal with the given toxen an 
the given circuit. 


RETURN VALUE Pointer to signal of the given token, 
or NULL if no match found 





PARAMETERS 
pcircuit Pointer to che circuit to search. If this 
is NULL, the current circuit is searched. 
page Page number to search. “O” means 
search the cursent page, “-1" means 
search all pagea. 
token Signal token to search for. 
t anew oe ee = eee = oe ee we re i ee ne re et ee Se 
«/ 
PQUALIFIER pTSignal MEDALockSigByToken( piCircuit pCireuit, 
short page, 
long token }; 
[ wenn n nee nn none n-ne nee ane en: ee eee eee - 
“MEDALookTypeByName” looks for a device type of the given name in 
the global list (shared by all open circuits) of types. 
RETURN VALUE Pointer to type of the given name, 
ox NULL if ao match found 
PARAMETERS 
fron Pointer to type after which to start 
searching. It this is NULL, searching starts 
fram the nead of the list. Passing the value 
returned by each call to successive cails 
searches for multiple instances of the name 
in the list. 
name Type name to look for. Caee is significant. 
Pee eee eee apn ae en re ee ee ee en re re ee ee ee ee Ae re ee << 
*/ 


PQUALIFIER pTType MEDALOokTypeHyName({ pTtype from, 


char *name ); 


[Nencocra-snenee= e2c----------~----- a Line 





"MEDALOokCctByName“ iooks for a circuit of the given name in the list 
of currently open circuits. 


RETURN VALUE Pointer to circuit of the given name, 
or NULL if no match found 


PARAMETERS 
fran Pointer to circuit after which to start 
searching. If this is NULL, searching starts 
com the head of the list. Passing the value 
returned by each call to successive calls 
searches for miltiple instances of the name 
in the list. 
name Circuit name to look for. Case is significant. 
Pee e cnc ee meee ce anne renee ener we nna ene e nnn sae cece nnn en mann ee ame enn ene e wees Oe 
*/ 
PQUALIFIER pTCircuit MEDALockCctByNams ( prtircuit fron, 


char «name ); 





“MEDAGetDevName” returms the name of the given device 


RETURN VALUE None 

PARAMETERS 

pDevice Pointer to the device in question 

name Returns the device name 

hier Set to TRUE to get a fully qualified name 


with the namas of all contazning hierarchical locks, 
FALSE to get only the nara of this 6ignal 


inclcetName Ignored if “hier” is FALSE. Set to TRUE to 
include the master cixcuit name in signal name 

Pence nnn ew oe a a oe rr rr em seer a ae ee ee ee ee - 
wf 
PQUALIFIER void MEDAGetDevName( prDevice pdevice, 

boolean hier, 

Boolean anclCctName, 

/*VAR*/ char ‘name ); 





“MEDAGetSigName” returne the name of the given signal 


RETURN VALUE None 

PARAMETERS 

pSignal Pointer to the signal in question 

name Returns the signal name 

hier * to TRUE to get a fully qualified nama 


with the names of all containing hierarchical biocks, 
FALSE to get only the name of this signal 





inc1CctNane Ignored if “hier” ie FALSE. Set to TRUE to 
include the waster circuit name in signal name 

tee nnn ean ee eee eee 5 a a a oe a eee a ee ee a ee a ee oe a a ee a oe ee ee 
+/ 
PQUALIFIER void MEDAGetSigName{ piCircuit pCircuit, 

prSignal pSignal, 

Boolean hier, 

Boolean inelLCctName, 


/*VAR*/ char *name ); 
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| ccadudesennanworreetennsesssene sna sec essence aes 
"MEDAGet TypeName" returns the name of the given type 
RETURN VALUE Nona 
PARAMETERS 
prype Pointer to the type in question 
name Returns the type name 
Wwe een we ow ee ee ee ome ee wre ren Se a a a ea oe a ae wee eee eee ——~--— 
*/ 
PQUALIFIER void MEDAGetTypeNane( pTType pType, 


/*VAR*/ char ‘name }; 





“MEDAGetCctName” returns the name of the given circuit 


RETURN VALUE None 
PARAMETERS 
pCircuit Pointer to the circuit in question 
name Returns the circuit name 
0 scat inane Se i en enh cn sin et ori af Sac e ce ae eee a een eenenecesaaenee sees 
«/ 
PQUALIFIER void MEDAGetCctName( piCircuit pCireuit, 


/*VAR*/ char *name }}; 





*MEDASetCctName” sets tha name of the given circuit 


RETURN VALUE None 

PARAMETERS 

peCircuit Pointer to the circuit to be named 

nam The new name 
Vee ee ee ew ee oe eee eee eww eee ee oe ee ee Se ee + eee = oe ee eee eee eee ee 
*/ 
PQUALIFIER void MEDASetCctName( piCircuit peircuit, 

char *name )}; 





“MEDAGatCctPageTitle” returns the title of the given circuit page 


RETURN VALUr None 
PARAMETERS 
pCircuit Pointer to the circuit in queation 
pageNum Page number in question 
title Returns the page title 
teen eee ee ene eee ee ewe ee ee = ee et ee ere eee A ee ee a ttt 
*/ 
PQUALIFIER void MEDAGetCctPageTitie{ piCircuit peircuit, 
short pageNum, 


/*VAR*/ char *title ); 





“MEDASetCctPageTitle” sets the title of the given circuit page 


RETURN VALUE None 


PARAMETERS 
pcircuit Pointer to the circuit in question 
pageNum Page number in question 
title The new page title 
*2-- eee == ee === --- == i es es eon meine ee wieetenanoaaseaease seam anancenennce we eennn 
*/ 
PQUALIFIER void MEDASetCctPageTitle( pICircuit pCircuit, 
short pageNun, 
char *title }; 





“MEDASetDevName” seta the name of the given device 


RETURN VALUE Nona 

PARAMETERS 

pCircuit Pointer to the circuit containing the given device 

pDevice Pointer to the cevice to be named 

name The new name 

visible TRUE to create visible name text on the diagram 

autoPos TRUE to automatically position the name near the 
device symbol. FALSE to use given position. 

udpate Type of screen update action desired. 

position Ignored unless visible ia TRUE and autcPos 14 FALSE. 


Determines position of nama on diagram in 1/1000" 


VW ewe wen nn = on ee wee oa a we eee essen on eee eee ee eee eee = 


*/ 

PQUALIFIER void MEDASetDevNama( piCircuit pCircuit, 
prdevice pdevice, 
char *name, 
Boolean visible, 
Boolean auto?Pos, 
tUpdateLevel update, 
Point position ); 





“MEDASetSigNama" sets the nama of the given sub-sagnal 


RETURN VALUE None 
PARAMETERS 
pcircuit Pointer to the circuit containing the given device 
pSignal Pointer to the sub-signal to be named 
name The new name 
visible TRUE to create visible name text on the diagram 
autoPos TRUE to automatically position the name near the 
signal line. FALSE to use given position. 
udpate Type of screen update action desired. 
position Ignored unless visibie is TRUE and autoPos is FALSE. 
Determines position of name om diagram 2n 1/1000" 
Wee oe a et ee eee eee = eee eee me ewe eee ewe we ee eee Heese a 
+f 
PQUALIFIER void MEDASetSigNama( pTCircuit pcircuit, 
pTSignal pSignal, 
char =name, 
Boolean visible, 
Boclean autoPos, 


tUpdateLevel update, 
Point position }; 
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Select and count operations 


Pee nme e nae we a ae ew esewne ene eee eee oo 


*/ 


]lzcwsssseateeeaeCese= 


eee en awe wae ee ee ew a en a ee eee eens 


mew nn meee wwe ne ene: 0 a a ae 





wae wenn me eee eee tee ene eee eeee= 


“MEDACountSigPins” returns the number of device pins 


connected by the given signal. 
RETURN VALUE Pin count 


PARAMETERS 


pSignal Pointer to signai in queation 

pageNum Count enly pina on devices on this page 
or -1 = ai. pages 

visOnly TRUE to count oniy pins on visible 


devices 


markedOnly TRUE to included only devices marked by 
a previous operatzon. 
selOnly TRUE to count only pins on selected 


devices 


inOnly TRUE to count only input pins 
(including bidirectional) 
outonly TRUE to count only output pins 
(including bidirectional, three state, 
etc.) This is ignored if “inOnly" is TRUE 
incl PseudoDevs TRUE to include pseudo-devices (i.e. 
breakouts and page connectors) in 
the count. Setting this TRUE and all 
other flags FALSE will give a complete 
count of ail pin records on this signal. 
sigConns TRUE to give a count of the number of 
signal connectors attached to this signal 
excluding all other device types. This 
overrides all other flaga except “visOnly". 
pageConna TRUE to giva a count of the number of 
page connectors and port coanectors on 
this signal, excluding all other device 
typea. This overrides all other fiage 
except “visOnly" and “pageConns”. 


| eee ry te a a ae eee em 


*/ 

PQUALIFIER tPinNum MEDACountSigPins{ piSignal 
short 
Boolean 
Beolean 
Boolean 
Boolean 
Boolean 
Boolean 
Boolean 
Boolaan 


pSignal, 
pageNum, 
visOnly, 
markedOnly, 
selonly, 
inOnly, 
outonly, 
incl?PseudcDevs, 
BigConns, 
pageConns ); 





“MEDACountSighines” returns the number o 


on the given signal. 


£ line segnents 


RETURN VALUES Line count 

PARAMETERS 

pSignal Pointer to signal in question 
pageNum Page number to restrict counting to 


or -1 # all pages 


*/ 


PQUALIFIER short MEDACountSigLines ( pTSignal pSignal, short pageNum ); 


“MEDACountDevs” returns the number of devices 
on the given circuit. 


RETURN VALUE Device count 
PARAMETERS 
peircuit Pointer to circuit to count 
pageNun Page number to restrict counting to 
or 0 = current page, -1 = all pages 
visOnly TRUE to count only visible devices 
markedonly TRUE to included only devices marked by 
a previous operation. 
selonly TRUE to count only selected devices 
incl PseudaDeve TRUE to include pseudo-devices (i.e. 
breakouts and page connectors) in 
the count. 
* en woneeeeeeseseerc=: eb Oe ah an a a a OO | ll ni a | Sana awe eS as aaae nee seem acpanie ige os om om a 
*/ 
PQUALIFIER long M=DACountDeve( pICircuit pCircuit, 
short pageNun, 
Boolean visOnly, 
Boolean MarkecOnly, 
Boolean selonly, 
Boolean inclPseudoDevsa ); 





“MEDACountSigs” returna the number of signais 
on the given circuit. 


RETURN VALUE Device count 
PARAMETERS 
pCircuit Pointer to circuit to count 
pageNum Page number to reatrict counting to 
or 0 = current page, -1 = all pages 
visCaly TRUE =o count only visible signals 
markedOnly TRUE to included only devices marked by 
a pravious operation. 
selOnly TRUE to count only selected signals 
¥ ew neewnenenee ween enn anno n eee en a en nnn nn ote nee = a ane eeewe nonce eee enenee aes 
«/ 
PQUALIFIER long MEDACountSige( piCircuit pCircauit, 
short pageNum, 
Boolean visonly, 
Boolean markedOnly, 
Boolean selonly ); 





“MEDACountCircuits” returns the number of circuits 
currently open. 


RETURN VALUE Device count 
PARAMETERS 
visOnly TRUE to count only visible signals 
# ne new ee ==---- 2 ne ea 6 noemase = eo nen n nee ne nnn ne ano ---- 


«/ 
PQUALIFIER short MEDACountC.zcu.te( Boolean visOnly ); 





“MEDAGetCctSelectiInfo” returns infomation about the currently selected 
circuit and page. 


RETURN VALUE TRUE if any circuit or page is open, FALSE if no 
circuit windows are open. 
PARAMETERS 
pCircuit Returns a pointer to the current circuit, or NULL 
if no circuit is open 
page Retuzns the page number of the page represented 
in the active window. 
Pancweenee meee se eamemae: i et i i ili ln i Sree ch ea en on- 
+/ 
PQUALIFIER Boolean MEDAGetCctSelectInto( /*VAR*/piCircuit *pCircuit, 


/*VAR*/ short *page }; 





“MEDAGetDevSelectInfo" returns information about the device(s) 
selected in the current circuit page window. 


RETURN VALUE TRUE if one or more devices are selected, FALSE if no 
device is selected 


PARAMETERS 
peircuit The circuit to check for selected devices. 
page The page to check for selected devices. 
pdevice If any device is selected, this will return 
a pointer to one of then, otherwise NULL 
numSelected Returns the number of cevices selected on 
the given page. 
Tene eww oes eoesoeweva: 0 ap an on an om a eo ow ee ee ee ee ee ee ee ee eS eee — 
+f 
PQUALIFIER Boolean MEDAGetDevSeectInic( prcircuit pcircuit, 
short page, 
/*VAR*/ pTDevice “ppevice, 
/*VART/ short *numSelected ); 





"MEDASetDevSelectinfo" sets the “selected” statue of the given 


device. 
RETURN VALUE nene 
PARAMETERS 
pcircuit The circuit containing the given device. 
poevice The device whose status is to be changed. 
update Screen update action to change hiliting 
selected New selected status of device 
tee eee = ao ae one ee ee ee ee re ee ee 
*/ 
PQUALIFIER void MEDASatDevSelectInfo( piCircait pcirenit, 
piDevice poevice, 
tUpdateLevei update, 


Boolean selected ); 





"MEDAGetSigSelectInfo" returns information about the signal(s) 
selected in the current circuit page window. If multiple signals 
are selected, this returns a count and a pointer to one of them 
(there is no guarantee of which one). More details can be 
extracted by using MEDAGetNextSignal, MEDAGetNextSubSigzal 

and MEDAGetSubSigiatfo. 


RETURN VALUE TRUE if one or more devices are selected, FALSE if ao 
device is selected 


PARAMETERS 
pCircuit The circuit to check for selected devices. 
page The page to check for selected devices. 
pSignal If any signal is selected, this will return 
a pointer to one of them, otherwise NULL 
numSelected Returns the number of devices selected on 
the given page. 
+ ane ee ewe = ee eo on ee ee eee ee eee ne ee eee ee He ee ewe eee see —_ 
*/ 
PQUALIPIER Boolean MEDAGetSigSelectinfo( pICircuit peireuit, 
short page, 
/*VAR*/ pTSignal *pSignal, 
/*VAR*/ short «numSelected ); 





"MEDASetDevSelectinfo” sets the “selected” status of the given 


device. 

RETURN VALUE none 

PARAMETERS 

pCircuit The circuit containing the given device. 

pDavice The device whose status is to be changed. 

update Screen update action to change hiliting 

selected New selected status of device 
Fewnewn anna nnn ene mination edeoes! Sie mit ink lai ab memeews nnn nen eno === = 
*/ 

PQUALIFIER void MEDASetS:igSelectintfo( pTCircuit pCircuit, 
pTsignal pSignal, 
tUpdateLevel update, 
Boolean selected ); 





"MEDAGatTextSelectinfo" returns information about the text item(s) 
selected in the current circuit page wincow. If multiple text items 
are selected, this returns a count and a pointer to one of them 
(thera is no guazantee of which one). 


RETURN VALUE TRUE if one or more items are selected, FALSE if no 
item is selected 


PARAMETERS 
peCircuit The circuit to check for selected text. 
page The page tc check fer selected text. 
plext If any text item is selected, this wiil return 
a pointer to one of them, otherwise NULL 
numSelected Returns the number of text items selected on 
the given page. 
tenn ec een nnn ~ i a sie eee ee ee ee ee ee er ee eee ne ern eee eran — 
*/ 
PQUALIFIER Boolean MEDAGetTextSelectinfo( prCircuit pcircuit, 
short page, 
/*VAR*/ pTText ptext, 


/*VAR*/ Boolean *numSelectad }; 


“MEDASet TextSelectinfo” seta the "selected" status of the given 





text item. 
RETURN VALUE none 
PARAMETERS 
pCircuit The circuit containing the given text item. 
plext The text item whose status ie to be changed. 
update Screen update action to change hiliting 
selected New selected status of text item. 
Pepe none ewecor anne ewe n—n-n---------- == Sie a a ei ad Aaaneeeeneesenee i i ton 
+f 
PQUALIFIER void MEDASetTextSelectinfo( pICircuit pCircuit, 
pTText pText, 
tUpdateLevel update, 
Boolean selected ); 
{ teweeee-------- oe 
“MEDAGetPictSelectInfo" returns information about the picture item(s) 
selected in the current circuit page window. If multiple picture items 
are selected, this returns a count and a pointer to one of them 
(there is no guarantee of which one). 
RETURN VALUE TRUE if one or more items are selected, FALSE if no 
item ia selected 
PARAMETERS 
pcirouit The circuit to check for selected picture. 
page The page to check for selected picture. 
pPict If any picture item is selected, this will return 
a pointer to one of them, otherwise NULL 
numSelected urna the number of picture items selected on 
tae given page. 
t es eoeeeeeeseces Seer saa aaa we Sew eee Ree eee <2 ap on on ee een eee Geto nieni yas mates event oan an ane 2.7 
+f 
PQUALIFIER Boolean MEDAGetPictSelectinfo( pICircuit pCircuit, 
short page, 
/*VAR*/ pTPict *pPict, 
/*VbR*/ short *numSelected );7 





"MEDASetPictSelectInfo" sets tha “selected” status of the given 
picture item. 


RETURN VALUE none 
PARAMETERS 
peizeuit The circuit containing the given picture item. 
pPict The picture item whose atatus is to be changed. 
update Screen update action to change hiliting 
aelected New selected status of picture item. 
+ aceon ee wae ee eee ee ee eee eee He tL . . . Se e eee ee ee see ee —— 
*/ 
PQUALIFIER void MEDASetPictSelectInfo( piCizcuit pCircuit, 
pIPpict pPict, 
tUpdateLevel update, 


Boolean selected ); 


Pe ew ee ee ee a er eee oe ee oe ee ee eee ee ee 
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Attribute operations 


General notes regarding attribute operations: 


~- In order to allow arbitrary length fieid contents, 
field values are returned as a pointer anc a 
length value. The pointer is pointing directly 
into the attribute data for the circuit structure. 
This data should never be modified directiy eince 
the format is not guaranteed and you will probably 
corrupt the contents of other fields. 

- The returned field length value is a signed 16-bit signed 
integer, so field values are limited to 32767 characters 
in length. 


- Field names can be any string of 1 to 15 characters 


containing any of the characters “0..9A..2Za. = 





“MEDAGetSigAttr” retrieves the contents of a signal 
attribute field given the field name. 


RETURN VALUE TRUE if the given field existed 
(even if empty), FALSE if it didn't 

PARAMETERS 

pSignal "wa signal to check for attributes 

fieldName The name of the attribute field to 
loox for 

fieldVaiuePtr If the specified fieid is <cund, 


(i.e. tha function returns TRUE) 
thia will return a pointer to the 
first character in the field vaiue 

fieldValceLen If the apecified field is found, 
thas will return the length of the 
field data. 


visible IZ the specified fieid is found, 


this will return the “visible” 
status of the field. 


+/ 
PQUALIFIER Boolean MEDAGetSigaAttr( pTSignal pSignail, 
tRefStr fieldName, 
/*VAR*/ pTAttrData ‘“fieldValuePtr, 
/*VAR*/ short *fieldValceLen, 


/*VAR*/ Boolean *vyisible ); 


fhewtnstdesscccdentetceesetesceenaseoeestesesoaee- 2 Secewan: wucvescersecnas 
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"MEDAGetSigAttrByIndex” allows sequential accese to fields 
without knowing the field nama. Tha index value should be 
pet to 0 before the first call to access the first field. 


Bach call will return an index value that points to the 
The index values will not necessarily be 


next field. 
successive integers and has no meaning to the caller 
except that it can be used to access the next field. 


RETURN VALUE TRUE if a valid field ia found at the given 
index, FALSE if the index points past the 
end of the last field. 

PARAMETERS 

pSignal Pointer to the signal in question 

index Must be seat to zero before first call. 
Returns index of next field which can be 
passed to subsequent calls to access 
the next field 

fieldName If a field is found with the given index, 
thie returns the nama of the field. 

fieldValuePtr If a fiald ia found, this returns a pointer 


to the first character in the field value string 
fieldValueLen If a field is found, this returmms the length 


of the field value. 


visidie If a field is found, this returns the “visibie“ 


tatus of the field. 


«/ 
PQUALIFIER Boolean MEDAGetSigAttrByindex( pTSignal 


pSignal, 
/*VAR*/ short *windex, 
/*VAR*/ tRefStr fieldName, 
/*VAR*/ pTlAttrData *fieldValuePtr, 
/*VAR*/ short *fieldValueLen, 


/*VAR*/ Boolean 


‘visible ); 





"MEDAGetSigAttrByValue” allows access to fieids by value 
without knowing the field name. 


RETURN VALUE TRUE if a valid field is found with the g:ven 
value, FALSE otherwise. 
PARAMETERS 
pSignal Pointer to the signai in question 
fieldName Tf a field ia found with the given va ue, 
this returns the name of the field. 
fieldValuePtr A pointer to the first byte of the value 
to search for. 
fieldValueLen Length of the value to search for. 
visible If a field is found, this returns the “visibie” 


status of the field. 


<7: 

PQUALIFIER Boolean MEDAGetSigAttxrByValue( pTSignal 
/*VAR*/ tRefStr 
prattrData 
short 
/*VAR*/ Boolean 


pSignal, 

fieldName, 

fieldValuertr, 
fieldValueLen, 

*visible }; 


°“MEDASetSigAttr” sets the contents of a field with the given name. 
If the field does not exist, it is created, if it does, the 

new contents completely replaces the old. The field value 

string is copied into the internal attribute block so it 

doses not have to be maintained by the caller. 


RETURN VALUES none. 

PARAMETERS 

pCircuit Pointer to the circuit containing the 
signal in question. 

pSignal Pointer to the signal in question 

fieldName Name of the field to add or modify. 


fieldValuePtr A pointer to the first byte of the value 
to copy to the new field. 
fieldValueLen Length of the value string. 


visible New “visible” status for the field. 
update Action to take to update the screen. 
Peewee meee enna eee ne ene e nna sense sno nenesnne= cee eve nenenanann enema eee wonw-- 
*/ 
PQUALIFIER void MEDASetSigAttr( piCircuit pAircuit, 
prsignal rSignal, 
tRefStr fieldName, 
ptattrData fieldValuePtr, 
short fieldValuelen, 
Boolean visible, 
tUpdateLevel update }; 
/t.--------------------------. ce rt se ei i a a hie sect on a 
"MEDADelSicAttr™ deletes a field with the given name. 
RETURN VALUE none. 
PARAMETERS 
pCircuit Pointer to the circuit containing the 
signal in question. 
pSignal Poanter to the aignal in question 
fieldName Name of tne field to delete. 
update Action to take to update the screen. 
4 eee eee wee eee eee Seow ee eee oe eer wot ee tweens HON Ree eeeeeseeseseesa: iis iis Since ih el ant ti rea ey 
*/ 
PQUALIFIER void MEDADelSigAttr( pICircuit pCircuit, 
pTSignal pSignal, 
tRefStr fireldNane, 


tUpeateLevel update ); 


| 





Pewee nn nee ee ee enna oo ee eee = oe ee 


"“MEDAGetDevAttr” retrieves the contents of a device 
attribute field given the field name. NOTE: This DOES NOT 
check the type or circuit attributes if the field is 

not found in the device. If you wish to implement 

such a search path (a la Report Generator) you have 

to call MEDAGetTypeAttr and MEDAGetCctAttr yourself. 


RETURN VALUE TRUE if the given field existed 
(even if empty), FALSE if it didn't 

PARAMETERS 

pDevice The device to check for attributes 

fieldName The name of the attribute field to 


leok for 

fieldValuePtr If the specified field is found, 
(i.e. the function returns TRUE) 
this will return a pointer to the 
first character in the field value 

fieldValueLen If the specified field is found, 
this will return the length of the 
field data. 

visible If the specified field is found, 
this will return the “visible” 
etatus of the fieid. 






f/f 
PQUALIPIER Boolean MEDAGetDevAttr( pTDevice pbevice, 
tRefStr fieldName, 
/*VAR*/ pTAttrData ‘*fieldValuePtr, 
/*VAR*/ short *fielaValueLen, 
/*VAR*/ Boolean *visibla ); 
[Bammer enn nnn en enn nn ew nn nnn nnn nn nn rn tn OOS 
“MEDAGetDevAttrByindex” allows sequential access to fields 
without knowing the field name. The index value should be 
set to 0 before the firat call to accees the firat field. 
Each call will return an index value that points to the 
next field. The index values will not necessarily be 
successive integers and has no maaning to the caller 
except that it can be used to access the next field. 
RETURN VALUE TRUE if a valid field is found at the given 
index, FALSE if the index pointe past the 
end of the last field. 
PARAMETERS 
pdevice Pointer to the device in question 
index Must be set to zero before first call. 
Raturns index of next field which can ke 
passed to subsequent calls to access 
the next field 
fieldNama If a field is found with the given index, 
this returns the name of the field. 
fieldValvePtr Tf a tieid ia found, this returns a pointer 
to the first character in the field value string 
fieldValueLen If a field is found, this returns the length 
of the field value. 
visible If a field is found, this returns the “visible” 
astatua of the Zield. 
Vee eee eee ee ee ee eee Ree eee = ep anes an apes am Ss si ao an amen en ee ee. eee eee ee eee eee ee eee woe 
*/ 
PQUALIFIER Boolean MEDAGetDevatt rByIndex( pTDevice pDevice, 
/*VAR*/ short “index, 
/*VAR"/ tRafStr fieldName, 
/*VAR*/ pTAttrData *f,eldVaiuePtr, 
/*VAR*/ short *fieldValueLen, 


/*VAR*/ Boolean visible ); 


] Racca ectendancnn a nnnwaneenasnnnnncsaananawae mand aaee 
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"MEDAGetDevAttrByValue” allows access to fields by value 
without knowing the field name. 


RETURN VALUE 


PARAMETERS 


pDevice 
fieldName 


fieldValuePtr 
fieldValueLen 
visible 


*/ 


PQUALIFISR Scolean MEDAGestDevAttzByValue( pIDevice 


TRUE if a valid field is found with the given 
value, FALSE otherwise. 


Pointer to the device in question 

If a field ia found with the given value, 

this returns the name of the field. 

A pointer to the first byte of the value 

to search for. 

Length of the value to search for. 

If a field is found, this returns the “visible” 
status of the field. 


pDevice, 
tRefstr fieidName, 
prattrData fieldValuePtr, 
short fieldValueLea, 
/*VAR*/ Boolean “visible ); 





"“MEDASetDevAttr” seta the contents of a field with tha given name. 
If the field doas act exist, it is created, 1£ it does, the 


New contents completely replaces the old. 


The field value 


string is copied into the internal attribute block so it 
does not have to be maintained by the caller. 









RETURN VALUE none. 
PARAMETERS 
peircuit Pointer to the circuit containing the 
device in question. 
poevioa Pointer to the device in question 
fieldNens Name of the field to add or modify. 
fieldValuePtr A pointer to the first byte of the value 
tc copy to the new field. 
fieldValueLen Length of the value stxing. 
visible New “visible” statua for the field. 
update Action to take to update the screen. 
Penn nn wecwccccce ecw enema onan cee nnn we een e we een nnnnnnnncoscone nts ms si a it 
«/ 
PQUALIFIER void MEDASetDevAttr({ piCircuit pCircuit, 
pTDevice plevice, 
tRefstr fieldName, 
pTattrData fie.dValuertr, 
short fieldValueLen, 
Boolean visible, 
tUpdateLevel update }; 
[Pawewewn mewn nen ne sewncee cn annnaneannnneonscoe= too a gs ene es wees ew as ow ik shi een ene 
“MEDADelDevAttr” deletes a field with the given name. 
RETURN VALUE none. 
PARAMETERS 
pcircuit Pointer to the circuit containing the 
device in question. 
pDevice Pointer to the Gevice in question 
fieldName Nane of the field to delete. 
update Action to take to update the screen. 
Vem wen een one oe oe eee eee ew ee A tS A I eee eee ee 
ef, 
PQUALIPIER void MEDADelDevattr({ pTCircuit pCizcuit, 
proevice poevice, 
tRefstr fieldName, 


tUpdateLevel 


update ); 
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“MEDAGetCctAttr" retrieves the contenta of a circuit 
attribute field given the field name. 


RETURN VALUE TRUE if the given field existed 
{even if empty), FALSE if it didn't 

PARAMETERS 

Circuit The circuit to check for attributes 

fieldName The nama of the attribute field to 


look for 
fieldVaiuePtr If the specified field is found, 
(i.e. the function returns TRUE) 
this will return a pointer to the 
first character in the field value 
fieldValueLen If the specified field ia found, 
this will setum the length of the 


field data. 
Pee ewe 6022222 eee eeeeene seeoena see cea: wena seers ae Bene we See Sew eww wee eee ——- 
*/ 
PQUALIPIER Boclean MEDAGetCsctAttr( pTCircuit pCcircuit, 
tRefStr fieldName, 
/*VAR*/ pTAttrData *fieldValuePtr, 
/*VAR*/ short *fieldValueLen ); 
| Benn ene con wen enn nn nn en eo on ee er nnn nn nana nena a <a ee om om te a ge ee a ee — 
“MEDAGetCctAttrByindex” allows sequential access to fields 
without knowing the field nama. The index value should be 
set to 0 before the first call to accesa the first field. 
Each call will return an index value that points to the 
next field. The index values will not necessarily be 
successive integers and has no meaning to the caller 
except that it can be used to access the next field. 
RETURN VALUE TRUE if a valid field is found at the given 
index, FALSE if the index points past the 
end of the last field. 
PARAMETERS 
pcircuit Poiater to the circuit in question 
index Must be set to zero before first call. 
Returns index of next field which can be 
passed to subsequent calis to access 
the next field 
fieldName It a field is found with the given index, 
thia returns the name of the field. 
fieldValuePtr If a field ia found, this returns a pointer 
to the first character in the field value string 
fieldValueLen If a field is found, this returns the length 
of the field value. 
% enw awe en eon e eee == cn etn A DP OSE Oe ow oe a an 00 Oo een am quam om ames om em a ee ee tp a gn on od a ee a oe a ene 
wf 
PQUALIFIER Boolean MEDAGetCctattrByindex( pIircuit pcircuit, 
/*VAR*/ short windex, 
/*VAR*/ tRefStr fieldNare, 


/*VAR*/ pTAttrData *fieldValuePtr, 
/*VAR*/ short *fieidValueLen }; 





“MEDAGetCctAttrByValue” allows access to fieids by value 
without knowing the field nama. 


RETURN VALUE TRUE if a valid field is found with the given 
value, FALSE otherwise. 

PARAMETERS 

pCireuit Pointer to the circuit in question 

fieldName If a field is found with the given value, 


this returns the name of the field. 
fieldValuePtr A pointer to the first byte of the value 
to search for. 
fieidValiuelen Length of the value to search for. 


Wee ee we he a ee = = == one eee a a ee ee a 


«/ 
PQUALIFIER Boolean MEDAGetCctattsByValue( pricircuit pCircuit, 
/*VAR*/ trRefStr fieldName, 
praAttrData fieldValuePtr, 
short fieldValueLen ); 





"MEDASatCctAttr” sets the contents of a field with the given name. 
If the field does not exist, it is created, if it does, thi 

Tew contents completaly replaces the old. The field value 

string is copied into the internal attricute block so it 

does not have to be maintained by the caller. 


RETURN VALUE none. 

PARAMETERS 

pecircuit Pointer to the carcuit in question 
fieldName Name of the field to add or modify. 
fieldValuePtr A pointer to the first byte of the value 


to copy to the new field. 
fieldValueLen Length of the value string. 


Www ee en oe ee a ee ee ee ee eee e== waeeenn ee ne ee ee ee eee eee 


/ 
PQUALIFIER void MEDASetCctAttr( piCircuit prircuit, 
tRefStr fieldName, 
ptAttrData fieldValuePtr, 
BnOrt fieldValueLen }; 





"MEDADalCctAttr” deletes a field with the given name. 


RETURN VALUE none. 

PARAMETERS 

pcircuit Pointer to the circuit in question 
fieldName Name of the field to delete. 


*/ 
PQUALIFIER void MEDADalCctattr( piCircuit pcircuit, 
tRefStr fieldName ); 


-99- 


[femme wnecnen anna nnn nn ne wen nnn en enn nnn ee ere nnnne nw en nen mne nnn nse ennnnnnceennneens 


“MEDAGatTypeAttr® retrieves the contents of a type 
attribute field given the field name. 


RETURN VALUE 


TRUE if the given field existed 
{even if empty), FALSE if it didn't 


PARAMETERS 
plype A poznter to the typa to check for attrisutes 
fieldNane The name of the attribute field to 
look for 
fieldvValuePtr If the specified field is found, 
(i.e. the function returns TRUE) 
this will retura a pointer to the 
first character in the field value 
fieldValuelen If the specified field is found, 
this will retum tha length of the 
field data. 
visible IZ the specified field is found, 
thia will return the “visible” 
atatus of the field. 
nT Te eee oe eee een an en eee </> anee a een en en ae: ecm ee 
*/ 
PQUALIFIER Boolean MEDAGetTypeAttr( pTType ptype, 
tRafstr fieldNaze, 
/*VaAR*/ pTAttrData ‘*fieldVaiuePtr, 
/*VAR*/ short *fieldValueLen, 
/*VAR*/ Boolean “visible ); 





“MEDAGet TypeAttr3yIndex” allows sequential access to fields 


The index vaiue should ke 


without knowing the <ieid name. 


set to 0 before the first call to access the first field. 


Bach cail will return an index value that points to the 


next field. The index values will not neceasarily be 
successive integers and has no meaning to the caller 
excapt that it can be used to accese the next field. 


RETURN VALUE 


TRUE if a valid field is found at the given 


index, FALSE if the index points past the 


era of the last field. 


PARAMETERS 
plype Pointex to the type in question 
index Most be set to zero befeoze first cali. 
Returns index of next field which can ce 
passed to subsequent calis to access 
the next field 
tieldNare If a field is found with the given index, 
this returns the name of the field. 
fieldValuePtr If a field is found, thie returns a pointer 
to the first character in the fieid value string 
fieldValueien if a field is found, this returne the length 
of the field value. 
visible Zf a field is found, this returns the “visible” 


status of the field. 





PQUALIFIER Boolean MEDAGetTypeAttrByindex( pItype 
/*VAR*/ short 
/*VAR*/ tRefstr 
/*VAR*/ pTAttrData 
/*VAR*/ short 
/*VAR*/ Boolean 


pType, 

“index, 
fieldName, 
*fieldValucertr, 
*fieldValueLen, 
*visible )}; 


“MEDAGatTypeAttrByValue” allows access to fieids by value 
without knowing the field name. 


RETURN VALUE TRUE if a valid field is found with the given 
value, FALSE otherwise. 

PARAMETERS 

plype Pointer to the type in question 

fieldName If a field is found with the given value, 


this returns the name of the fieid. 
fieldValuePtr A pointer to the first byte of the value 
to search for. 
fieldValuelen Length of the value to search for. 


visible It a field is found with the given value 
this returne ita “visible” status. 
Peewee nn en nn re ew ne nn nn nee iin nom cians) te 
«/ 

PQUALIFIER Boolean MEDAGet TypeAttsByValue( pIType pType, 
/*VAR*/ tRefStr fieldName, 
eTAttrData fieldValuePtr, 
short fieldValueLen, 


/*VAR*/ Boolean *visible ); 


-101 - 


Appendix B - The MEDADebug Library 


| Rem en n a one ew en nn en nnn nnn nnn nnn oeeennn--- oe ee nn ee ween 
* *KeyPressed” returns TRUE if the given key number is pressed. Xey 

* numbers are defined in the EventManager. *) 

Wen w nnn n eee n-ne e--- === === === seen ee een nase eneaemenemacwon eee a 
~/ 


PQUALIFIER Soolean KeyPressed( short keyNum ); 


| ao a> op am a om ee amenene oo op a aoe a sen neen= 
* "ppOutInt® writes the given string to the debug window, followed by 
* the given integer in decimal 
ieee ee ain es emia mere: wa cen ee et ee enn ee ne ene eee nnnne== 
*/ 

PQUALIFIZR void DBOutint( char ‘iisg, short num ); 

[ tecenn nen neneerenn----e= a a om i i a papas ven 
. “DBOutPt" writes the given string to the debug window, followed by 
e the given point, in decimal, in the order x, ¥ 
to ncecennnnnnnen scatacnaceaucen Seacnansanasce ae esate con ins co Ean a 
*/ 

PQUALIFIER void DBOutPt( char *msg, Point pt }; 

{tan ee worn nnn e =. Oe en a ee enone eae wre wen eee oe nw eee een === = = — 
* “pBoutstr" writes out the two given strings, concatenated together 
Yeaeen= = ee == ee oem am on om om an oe oe a we ~~ nn ees ee eases. ——- = a 
«f/f 

PQUALIFIEZR void DBOutStr( char *msgl, char *msg2 }; 

[tenon o ese ------- =~. iétnmnsnaseces) wekeeccenc cet ebeenensecececcclcceesesees= 
* “pBoutRect" writes the given atring to the debug window, followed by 
* the given rectangle, in decimal, in the order left, top, right, bottom 
Po ee ere eee eee eee eee ee eee eee = Seaman wew en eee ee eee wee = ee ee ee ee ———_ 
*/ 

PQUALIFIER void DBOutRect( char “msg, Rect rect ); 

[Wanna een cena nn nn enn enn non ce nnn nnn nee nnn nn n= ee picieiics iae icine 
* “DBOutAddr” writes the given string to the debug window, followed by 
* the given address, in hex. 

CRemeen eee eee eee eee eee ee se e069 ae aa as os ee a a ee eo eh a ——— 
*/ 

PQUALIFIER void DBOutAddr( char *msag, Ptr adr j; 

[tacweesennneneo= were en enn nn an nnn nnn nnn nnn nnn eee een nnn enw enwe me 
* “pSTrace” writes a single character to the debug window 
toe eee oo a a ane ee Re Re aan wn eee we een 2 ee eee eee 
*/ 

PQUALIFIER void DBTrace( short c }; 

| ee ween wenn nnn nee w= === ee eee eee == 
e “pBOutDestList” dumps a notification list held by the GateXeeper. 

* 

* miscAddr 1s an address that will be included in the dump. 
2 dest dead points to the destination list. 

* paModu le is a module address to match on, or 
- NIL to dump all modules. 

* refCon is a refCon value to match on, or NIL for ail 
Veccennnnnwwesaeann--=-- Sseneonenes ieee Smee ie cares eae e oe mee 
/ 


PQUALIFIER void DRBOutDestiist( char *msg, Ptr miscAddr, Ptr destHead, Ptr pModule, Ptr refCcon )7 
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[Ba ewcn nen necnn nnn enn on ne nen nnn nnn en nn nnnnn nena nnaen ecco sacenos “ 


* "MEDAMessageError” causes the GateKeeper to put up its standa. 

* message error alert box. This box displays the given error text 

* string, followed by a hex representation of the given address, 

* followed by the message type and name of the source module, 

* derived from the given message. 

Can mececscesenconennn: eS emenec cece we scsi ad icin ce Dal a ms pc nl sas 
*/ 


PQUALIFIER void MEDAMessage=rror( piMsgHeader pMsg, Ptr errAddr, char *errText }; 


[Bannwe nna nne nnn nen nnn n enna nee nnn nena n ne po Sal entnae ae etes = 


* "DROutText” writes out the character string “str” followed 

* immediately by the string of characters pointed to by 

e “textPtr” ani of length “textLen". This is used to dump 

e arbitrary length character strings to the debug window. 

ene ee eee = eee See eee ee a ween ween oe eee we se we eres cee ts fees ees onan 
*/ 


PQUALIPIER void DBOutText( char ‘str, Ptr textPtr, short textLen }; 


[tanvee-n ee on nn -- === === eee Anomoe pee e neem ene ena eee e en nneneeeeen= 
"MEDASendTextMessage” unpacks the formatted string given 

into a massage recoxzd and serds the message. The "sroModule” 

field of the sent message will be the original senders address. 

If “pMsq" is rnon-NIL than the message header is copied to the 

given address after the callec module returns. This can be 

used to check the “handled” status, dest moduie address, etc. 


The message text ia of the foliowing form: 
{fieldType fieldVal) (fieldType fieldVal)... 


The “fieldType” and corresponding value data is as follows: 


fieldType fieldval 
M Message type (two characters) 
B Bytes value in hex 
Ww Word value in hex 
L Long word value in hex 
s. Character string (not padded) 
snn Character string padded to given length 


Character etrings may be given in single or double quotes, Or 

if no q™uctes appear, are taken to begin with the first non-Slank 
character after the fieldType and end with the last non-biank character 
before the closing parenthesis. 


The message type is placec in the massage header “megType™ field, 
the “dstModule" field is set to the address of the calling module, 
and the other header fielde are set to null values. The remaining 
data fields are packed according to the iengthe given and attached 
to the message after the header. 


teen e eee eet ee te et eet et ek a et 


=} 
PQUALIPIER void MEDASendTextMessage( char *text, piMsgueader pMeg ); 
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Appendix C - The MEDAInit Library 


| SGcmmonseet esses vsatesetse le ces = ene aa imacboooes 
* “MEDAInitMessage” is used to fill in the appropriate measage fields in 
* response to the initial “Im” message. it first checks the incoming 
* MEDAVeraion field to make sure it matches oura, returning FALSE otherwise, or 
* it “okToRun" is passed a FALSE. 
* 
* NOTE: Unlike most of the other library routines, 
* MEDAINitMessage does not actually send a meseage, it merely fills 
* in the fields so they will be correct when the module returns after receiving 
* the “Im". 
0 eee OO RAR ae Eee wwe Heenan anaaeaanaoews» ew eee meee ee een ee eee eee ee <2 pan oe eee ee 2 
*/ 
PQUALIFIER Boolean MEDAInitMeseage( oTInitMsg pMsg, 

short messageType, 

Ptr refCon, 

char walias, 

Boolean okToRun, 

Boolean startAwake, 

Boolean userInviaibie, 

Boolean wantIdle, 

Boolean needResources, 

Boolean wantHignievel }; 
JO en re pa a oo no ae en ee ee ne enn nnn enn = Aa ae ee eee eee: ae ee re 
e “MEDAInit” initializes internal variables in the MEDA librazy package. When 
* linked to a Modula-2 module, this does not need tc be called since it is 
* called autematically by the initialization section 
teen ene ee ee een Oe eee Se See we 8 ee He eee eee eee oot a ee ee eee eon enon ome on oe ee ae a 
+f 


PQUALIFIER void MEDAInit( void }; 


[*ewener------- +o nn ene nnn eee nn nnn nn eee eee = io ieebewoea 
® “MEDASetAwakeStatus” sets the awake status of the calling module 
Taeeoeseseeeeeese=: se 9p a a ee ee a a a eam 
sf 

PQUALIFIER void MEDASetAwakeStatus{ Boolean awake ); 

ft ckeeeeee ae, sii ee i wa it ne eanesaeemusan 1 Gis eimai este Sadia hema aie are Sei ew amen 
* “MEDAAddNotifyDest” adde a destination module to the given notify list. It is 
* the caller's responsibility to ensure that “destHead” is NIL the first time 
* this is called for a given list. “destHead" will be updated to point to the 
* first item in the list the firat time this is calied 
Poeen eee wen seme ann seem ewd eee sae eee ese ee= eee seas seewsee hs lip es eel ard eae eee wes ase onewe a= 
«/ 

PQUALIFIER void MEDAAddNotifyDest (/*VAR*/ Ptr *destHead, 

Ptr pModuie, 
Ptr refCon, 
tRefStzxr mask ); 

[to---220------------- erccncenccecann nen enewerns seme ceneewa cemeneere——seeeeecocesan 
* “MEDANOtifyEnquire” returne TRUE if any moduie on the given 
* notification list would be called for the given message 
* type character. 
tween enacanennnne aha sch a ct i ot ct ee wwe nme ne eee -annenne sane iniaomiccon ome 
*/ 


PQUALIFIER Boolean MEDANot:fyEnquize( Ptr destHead, short message ); 


[*amenene---202------------ eT ee enneneneeccncnnane 
* "MEDADelNotifyDest~ deletes all entries in the given list with 

* the given “pModule“ and “refCon”. zither “pModule" or “refCon" 

* can be passed as NIL, in which case that field is ignored, 

* and all entries matching the other field are deleted. Setting 

* poth to NIL will delete all entries. 

*« 

* It is the module's responsibility to delete these entries 

* when they are no longer needed. Tha GateXeeper never deletes them. 

Te ee ee en ae 2 ee a a eee eee ee woee-e ee ad 
sf 


[fewnnn nen nnnnn en ---- non nnn nnn nnn ne enn nnn nnn nnn facia ae none i a ee weeeneeesennne nies 
* °MEDAFindModuleByAlias” zeturne the address of a module, given its 

* alias (the string returned to the GateKeeper in initialization. 

bad Returns NIL if no such name found. 

# mewn one n-ne === ===: oh ia i ween ne nn ene nee nee sim a - 
+/ 
PQUALIFIER Ptr MEDAFindMoculeByAlias({ char *alias ); 

[Barn me nnn nwa nnn nee nn nnn tenn nn en nn nen nnn nr nan nan anne wane ns ene w enn nneaeeen 
* “MEDAFindModuleByMsg” retums the address of a module, given its 

* message type character (the character yeturned to the 

* GateKXeeper in initialization. Returne NIL if no such name found. 
eee one eee: ee a oe oe oe ae om oe ert ees ee ew eee —— 
*/ 

PQUALIFIER Ptr MEDAPindModuleByMsg( short msgClass }; 

es exatae dereamennemaet! ee Rear boone line picnics enim eonecenne 
* “MEDAWakeUpModule" sends a wake-up ("Iw") message to the module 

* with the given address. Returna TRUE if the other MOGLe 

* was found and handlec the message. “object” is the acdresa 

* of an abject to open, “cpenNew" ie TRUE if a new window is 

= desirec, aa opposed to merely displaying an o1d one. 

e NOTE: The interpretation of “abject” and “openNew" is in fact 

* entirely up to the sending and receiving modules since no-one 

* else is going to icok at them. If you need to pass more parameters, 

ky you can use “object” as a pointer to a parameter biock whose 

* format is agreed upon by both parties. 

mew ee nen ee ew oe ee ee eee een ni ln ee ap an ee ee a a Oe oe eee ee: ween 
af; 


tte ae eww eee nn an eee eee amen ns owen as een eaten 
“MEDANeedResources” allows the module to turn its “need resource file” 
* statue on and off. MEDA calls operate much more efficiently if this 

* jie turned off. If “need” is FALSE, the GateKeeper will not restore the 
* current resource file setting upon return from this or subsequent calis 
4 
. 


* 


to other modules (the module can atill call “UseResFile* on ita own 
if needed). If “need” is TRUE, than the current resource file wili 


* be sat on return from this and subsequent calis to other modules. 
8 weer aenn---- onan enema soe a oaeene ann ne ean ee peewee anne wanoccsnn= ee 
*/ 


PQUALIFIER void MEDANeedRescurces{ Soolean need }; 


ee Sccadil ei at ecliceienecten ices Ries ae cil i i hn irc all a 
* "“MEDALOCadModule" takes the given handle to a single-block MEDA code 
* module and intalls and initializes the module. If “resFile” is non-zero, 
* it is taken to be the resource file ID of the (presumably open) resource 
* file to be used for this module. If “resID“ is non-zero, it is taken as 
* the resource [D of the DRVR code block for thia medule. If this is 
* provided then the module will be purgeable when not awake. 
* The address of the loaded modula’s info 
* block is returned and can be used to address subsequent measages to 
e the module using the “dstModule” field in any message. 
* “object” is passed to the module in the “imObiect" message field. 
PV woeeenwoeeeeeeces==: Ow HOSE RESTS UEC ECO EEE eee et ee ee ee ee ee eee eee ee 
/ 
PQUALIFIER Ptr MEDALoadModuie( Handle codeHandle, 
short resFile, 
short xresID, 
char’ *name, 
Ptr object ); 
fWacewcccccocans sancocansananesunncacesssossjcosese NOL ReeahnsS Soe we heeennce waa —_ 
e “MEDALOadFileModule” loads any MEDA modules({s) in the given resource 
. file and intalls and initializes them. “resFile“ is taken to be 
* tha resource file ID of the (presumably open) resource 
* file to be used for this module. 
* The addreas of the loaded module's info block ie returned and can 
* be used to address subsequent messages to the module using the 
* “detModule”“ field in any massage. NIL is returned if any error 
* occurred in Loading. 
- NOTE; It ia possible for the file to contain more than one DRVR 
* module. In this case, all modules are loaded and initialized, 
* and the returned pointer will point to the last one found. 
* “name” is the user-visibie name for the module. If this is ampty 
. then the module will not appear an the Module menu. 
* “object” ia passed to the module in the "smObject" message field. 
9 9800882 082 0882808082888 8 88 8882C8 2688S COE COEe 88 608 6988 28 8 Oe eee Re eee Dewees seeseren 
*/ 
PQUALIFIER Ptr MEDALoadFileModu le ( short xresPiie, 
char *name, 
Ptr opiect }; 
f Be nn on on oo nn on on 3 on 5 oo os en ee ee re en ne en rn ree see ssses= = 
* “MEDAUnlLoadModule” sends the module an "exit" message and deallocates 
* any global storage used by the module. ‘The module's cede itself is not 
* deallocated as it is considered to belong to whoever mace the init.as 
* load cali. 
tf eeweweeweeewweeweoweweswuvewoewoures: es i lin esl nc an ci eS" te ig th Wh ak a oe aeeeeneseawew ene 
*/ 


PQUALIFIER void MEDAUnioadModule( Ptr module ); 





/ 


ON ss cag sal aia agent aati ine be tn 
* “MEDAInitModule” sends the module an “exit” message and deallocates 

bad any global storage used by the module. The module is then completely 

* rewinitialized, including allocating global Gata, as if it had just 

* been loaded. The function returns FALSE if any error occurs, 

* euch as not being able to allocate the global data. 
Tteeveeneeeeeeeeeeen seen we eeee ee eeewewwawuwwera a eee eee eee eee eee 
+/ 
PQUALIFIER Boolean MEDAInitModu le ( Ptr module ); 

| rt Jencianoaasenae ie 
* “MEDALockModule" sets the module's “locked" status to that given. 

- Once lockad, a moduie's code will not be purged at any tine. 

* tf the module has been purged, then it is reloaded at the time 

7 of the call. The function returms FALSE if the module is being 

* locked and cannct be loaded for lack of memory. 

€ eww ewww ee eee eee eee wee eee eo eee eee eee we ew eee oe a a ee eee eee 5 ees ee seer re n= ——— 
*/ 

PQUALIFIER Boclean MEDALOcKMcdcule( Per mnegule, 


Boolean locked }; 


[Biasesecenee eee os eenwee da cacoswseee Sos cusSS: ae a ee re 


. 


*tetnee & & 
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“MEDAQUIit" causes the program to quit. If “force” is FALSE, 

this routine will return and a Quit sequence will be executed 

on the next pass through the main event loop. This 

call is equivalent to selecting the Quit menu item in that it 

allows the user to cancel if changes have not been saved. If “force” 
is TRUE then an exit “Ie” message is sent to all modules 

(including this one} and an exit is done immediately regardless 

of whether any modules returned a “dirty” status 


Woe oe ee oe ee ee ee = a ee eee ee eee eee oe oa ee ee eee eee He See a ee 


*/ 


PQUALIPIER void MEDAQuit( Boolean force ); 


2407 4 


Appendix D - The MEDALibs Library 


(To be added) 
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Appendix E - The MEDAMenus Library 


| Brew nw wow nnn en tn en nena nanan = eed Aaa ee eee ee 
* "MEDAAddMenu” looks for an existing menu of the same name as the one 

. given and adds the items in the given menu to it. If no such 

* manu already exiata, it is added tc the menu bar. *) 

Va mee wee ewe ew = oe eee 6 ae ee oe een eee LE SS 
*/ 


PQUALIFIER void MEDAAddMenu( Ptr menu ); 


[ Paccnn nnn nen ewe ene---- see n= === === eee cenenn nn een == === a he i eceeccceee=== 
* "MEDARemoveMenu" removes the given menu from the GateKeeper's menu 

* list. If other modules are associated with the same menu items, 

* those items will still remain in the menu bar. 

Pecncowe wane ween nna nn eon i oi sin a a smi a it phn ci oi cist —e 
+f 

PQUALIFIZR void MEDARemoveMenu({ Ptr menu ); 

en ji pia ein ie ie ap cheer ices: one we eee wenn n a od 
* “MEDAAddMenultam” adds a single manu item to the given menu. The 

* value “itemNum” is of significance only to the module. it is 

* returned to the moduie in a menu notification to identify the 

of item hit 

Peeencencnneen non nn anno n een ennnnen= wet eee ee ee ee er ee ee nn eee ne nnn 
*/ 


PQUALIFIER void MEDAAdcMenultem( char *menuName, char *itemName, short amdChr, short itemNum, Soolean 
disable ); 


{t--2ncce-----. wane mee eee eee eee we wewenenen= oe ee ee ee ee ee ee eee en a 
* “MEDAAGGPrivateMenu” xequests the GateKeaper to send any nits 

* on the given menu on to the module. The GateKeeper does not 

sal create them mans or update the menu Dar 

¥ ame wer nnn ne een nnn en ne 2 nn nn nn enn nner en anne i a ie ee ii sowie 
*/ 


PQUALIFIER void MEDAAddPrivateMenu( Ptr menu, short menuID, Boolean disable ); 


* menu list 


Vw ewe ee eee eee eee = 
«/ 
PQUALIFIER void MEDARemovePrivateMenu( Ptr menu, short manuID ); 





/*----- edi cain peaiaee a a a euce aera we eaaieeicseieted eisai a iain Suieane cue oes 
* “MEDASetmenultemStatus” sets the “checked” and “enabled” status of 

* the given menu item in the given menu. If “setEnable” is TRUE 

* the enable status will be set according to “enabled", otherwise it 

* is left unchanged. Likewise, if “setChecked” is TRUE, the checkmark 

* status will be set according to “checked”. 

Peewee ee ee eee ne ee eee eee eee eee eee 2 oe oe eo an oe a a se ee re ee oe ma 
wf 


PQUALIFIER void MEDASetmenuiterstatus { short menuld, 
short item, 
Boolean enabled, 


Boolean checked, 
Boolean setinab-e, 
lean setChecked ); 
| tewwe noose === -- === www eee eee nee eene ome eceew—eeeene wee oe ee ee eee nee 
* “MEDASetMenultemText” sets the text for the given menu item 
Pee ee ee ewe eee one eee eee eo a ee eee eee ww we oe ee ee en eer 
*/ 


PQUALIFIER void MEDASetMenuItenText ( short menuID, short itemNum, char *text ); 
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| fawn n nen one enn nnn se nnn nanan eee ew ee ee oe eee a eee a cs cm ee Oe eee tee - 
* "MEDACheckMenultem” adds or removes a check mark no 

* the given menu item. If this item is shared by a number 

* of modules, theee settings only affect the menus when 

* this module is active. : 

* 

+ Parameters 

* 

® menuID The ID of the module's menu resource that 

. was used to create this item 

* itemNun The item number for the item to be changed 

* checked TRUE to turn on check mark, FALSE to turn off 

Pee eee eee ee oe en nee ene ee ee eee a oan ew ee oe ee ee tl 


«f/f 
PQUALIFIER void MEDACheackMenultem( short menuID, short itemNum, Boolean checked }; 


ne ett eed ~eaeewe weeeee ee ee ne ew a eee ee eee 
* "MEDAENableMenuItem” enables the given menu :tem when the calling 

* module is active. 

4 wwe nee wo ee oo ee ee on on oe ow wea meme = 2 en es en we ee ee ee eee eww sere 
*f 


PQUALIFIER voic MEDAEnableManultem{ short menuID, short itemNum ); 


[Mawnan nse e en nnn ee nnn ne en nn ee ten nnn enn cnn n ernest a= aaaa—= nee ween nnn na=== 
* “MEDAEnableMenulItem” disablea the given menu item when the calling 

* module is active. 

ta nemnwnnn—=: ee waneoon ee ee we eee ee een n eee === oa oe 
*/ 


PQUALIFIER void MEDADisableMenultem( short manuZD, short itemNum ); 
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ppendix F - The MEDASimulate Library 





[Uancacenenncesoen ean canenandencce ner enna cccnusere se cnenenssennnacmenae gence teasaa 





et et ee a 8 ee eee a Se ee ee we eee ee ee ee eee 


"MEDASimulateAvailable” determines whether the simulation module 
is available, i.e. whether any of the other calls in this 
livrary will succeed. Since the user can configure a system 
without the aimulation module, it is important to make this call 
before assuming that any of the other “MEDASimulate” calla 

will work. If this returns FALSE, and you need other calls 

to proceed it is up to you to put up an appropriate error 

box and bail out gracefully. 


* 

RETURN VALUE TRUE if MEDASimulate ia available, 

FALSE otherwise. 

* 

PARAMETERS 
* 

none 
0 em wee ww wetww8 GOO O00 CON O8S Bee Owes se ses ee wee~wewese8ee seeeeseesesrn& i —_ 
*/ 


PQUALIPIER Boolean MEDASimilateAvailable({); 


[Senne nnn nee ewe enn en inne n= n= ee eee ew nnn nn === a ce td pi ie 
* "MEDASetUpSignalivent” adds a signal change event to the queue 

* for the given circuit for the given signal with the given 

* source pin. If the device and pin are not specified (NIi and 0 

* respectively) then the signal's value is changed without affecting 

* the scurce valuea of any of the driving devices. The time 

- value specified is relative to the current time. 

Yt eee eee we we eH ee ee ee ew oo te eee eee eee 2p an a a a a Oa oD OD oe e.nnaneanes 
*/ 


PQUALIFIER void MEDASetUpSignalEvent( piCircuit circuit, 
pTSignal sigNet, 
piDevice device, 
ctPinNum pin, 
long tine, 
tSigVal value ); 


* "MEDASetUpStuckEvent” adds a signal change event to the queue 
- which will cause the signal to be “stuck” at the given state, 
* i.e. it will not change theraafter as a result cf device cutputs. 
* Subsequent calla to “MEDASetUpStuckEvent” can be used to change 
* the value and leave the “stuck” status intact, or to 
* “MEDASetUpUnatuckEvent” to remove the “stuck” status. 
9 eee we eee nw eee eee ewe eee wwe ere See eee eee ewe=: —- 
v/ 
PQUALIFIER void MEDASetUpStuckEvent( poCircuit circuit, 
pTSignal sigNet, 
long time, 
tSigVal value ); 


Jt eacasce dower seteeeecccucs ee ae a Cendant acacia ve ann awe tains we: 
* "MEDASetUpUnstuckSvent” sets up a signal event to remove the 
* “stuck” status and change the value to the given leve.. 
¢ eee. A SO ae a a a a a wee wee ene ee eee 
*/ 
PQUALIFIER void MEDASetUpUnstuckEvent( pICircuit circuit, 

pTSignal sigNet, 

long time, 


tSigVal value ); 
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Fe Pa ae a ee 


* “*MEDASetUpPinEvent” is the same as “MEDASetUpSignalEvent” except 
* that the signal pointer is derived fram the source device and pin number 
* and does not naed to be supplied by the caller. If “time” ia 
* gat to -1, then the delay ia taken from the device. 
© ee ee ee ee ew ew wo on a a ow rr eee 
af f 
PQUALIFIER void MEDASatUpPinavent( piCarcuit circuit, 
peDevice device, 
tPinNum p2a, 
long time, 
tSigVal value }} 
ee oie ee ene eee nano ee eee nn He 
* “MEDADisposeEvent" disposes of the given event record. 
* NOTE: Currently, the ony way to get an event pointer is 
. with internal knowledge of the circuit structure. 
# ween a8 +--+ nn ee ee - - 5+ oo e-= + 2  e ee 2 = === == === 
«/ 
PQUALIFIER void MEDADisposeEvent( pICircuit circuit, 
prEvent pEvent ); 
[Raw ww men nnn ene nn-- === =~ == a tc a a a a a a eo ewe we we eee 
* “MEDASeatUpDevicelivent” places a device event on the quene 
* which will causa the device to be re-evaluatec at the given 
. time regardless of whether any inputs have changed. The given 
* pin number and signal value are passed to the device mcdel 
* 


and their interpretation 1a device-type dependent. 





PQUALIFIER void MEDASetUpDeviceivernt{ pitircuit circuit, 
pIDevice Gevice, 
TPinNum = pln, 


long time, 

tSigval value }; 
[eewennnn nn 3 nnn 2 enn nn nnn 3 nnn nn nnn nn nnn nn enn nn nnn nn nn enn nnn 
= “MEDADeviceChanged” flags the given device to be re-evaluated 
- during the next pass through the aimulator even ii none if 
* ute inputs have changed. This is done if some interna: state 
* or logic of tha device has changed. 
Fawn ee ee = ah ak ae oe a oe ee ee eH ewe ee eee 
*/ 


PQUALIFIER void MEDADeviceChanged( piCircuit circuit, 
piDevice cevice ); 





[¥en e nee nne= ca ROT eee Dee ewan awa eewen een eneeser eee 
* “MEDASignalChanged" flags the given signal to be re-evaluated 
* during the next pass through the simulator even if there is mo 
= event on it. This is done if same strictural change has taken place. 
Pewee enna nnn ene nnn nnnn a= - === ane ane neenceeen— a eene weno ee oti a tino a 
+/ 
PQUALIFIER void MEDASignalChanged{ pTCircuit eircuit, 

prsignal signal );7 






* “MEDAIsInputPin” returns TRUE if a level change at this pin couic 
* cause the device to be re-evaluated. 





* “MEDAIsOutputPin” returns TRUE if the given device pin coula source 
. a 8ighal vaiue change 

Wee en we oe en eens e sree ae ee ee eR eee ee eee een 
=f 


PQUALIFIER Hoolean MEDAIsOutputPin{ pTDevice cevice, tPinNum pin )?; 
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[Bowen nnn enn nnn nn enn ene nnn nnn senna nT ry 
* “MEDAGetSignalRange” returns a positive integer value for the signals 
. on the given range of ping. “iSBPin" and "MSBPin" specify the pin 
* numbers for the lowest and highest bite of the number. “iSBPin" can 
* be greater or less than “MSBPin”, but che number of pins must be 
* less than 32. I~ any pin has an unknown value on it, the value 
* <1 is returned. 

& wee we oe a a ee 8 8 a a eee ee Hee eee eee “— 
«/ 


PQUALIFIER Long MEDAGetSignalRange{ pTDevice device, tPinNum LSBPin, tPiaNum MSBPin ); 


[fan mn enn nnn nna en nn enna nnn nan nn ns tn jac 
. “MEDASetSignalRange” sets up signal values on the given range 

* of pins to represent the given integer. “LSBPin" and “MSBPin“ epecify the pin 
e numbers for tha lowest and highest bita of the number. “LSBPin" can 

* be greater or less than “MSBPin“, but the number of pins must be 

* less than 32. 

¥ ewe nn een oe oe = = = = a cen on ew eo eween- ee wee eee ee ee ee re eee ee aan = 

*/ 


PQUALIFIER void MEDASetSignalRange( pitircuit circuit, 
pTDevice device, 


tPinNum LSBPin, 
tPinNum MSBPin, 
long value }; 


[ Baw nnn enn oan nn en nnn ne ar ee a os 
* “MEDAGetSignal0ldVaiue” returns the “ola” value of the given 

* signal. Note that the old anc new values of a signal are oniy 

* diffezent during the evaluation of device routines in the simulator 
tomar ee eee <<< = a eee ee _—— ee eee eee = - 
«/ 


PQUALIFIER tSigVal MEDAGetSignalOldValue( pTSignal sigNet); 


[tewennno = nee ee oe see == -s 2 - = ee ae gecceececesecccecacceenas 
* “MEDAGetSignalNewalue” returna the “new” value of the given 

* signal, that is the value taking into account events that were 

* taken of the event queue at the current time. 

Bre ee ee een nn nn ne nnn nn een nn ener a ome eam wr = 
«/ 
PQUALIFIER tSigVal MEDAGetSicnaiNewValue{ pTSignal sigNet }; 

[ tenner enn ean nnn nnn nnan enewen = oe oe meme ee ee ee nen enn 
* “MEDAGetSignalValues“ returns both the old and new values 

* for the given signal as VAR parameters 

Reem mn ewe eee ee eee eee eee eee ——— oe ewe we eee w= 
af 


PQUALIFIER void MEDAGetSignaiVaiues( ptSignal sigNet, /*VAR*/ tSigVal «new, /*VAR*/ tSigVal *old ); 


| Wenn nna enn non n-ne eee en nnn enn nn nnn ne nnn nn + nn nnn enn 
* “MEDAAddSimNotify" sets up a notification request on the given 

2 ject. Tua “refCon” value wiil be placed in the “obj RefCon" 

* field of a notification message when it occurs. The “mask” string 

* spacifiea the second Letter of any meseage types the caller 

* wante to receive. 

tanner eee ewe ees: nen mene saan ee ewe on wee ee we eee ee eee ee 
*/ 


PQUALIFIER void MEDAAdGSimNotify( Ptr object, tObjectType type, Ptr refCon, char *mask ); 


[tacenw nnn nanan anne een one ==-= wicca i comeconw ania: benaccacdechectene cect 
# "MEDADelSiaNotify"” deletes the given notification request 
ee fo eee rene eee pacer nnn nn pane ener eee nena “= 
*/ 


ALIFIER void MEDADelSimNotify( Ptr object, tObjectTybe type, Ptr refCcon ); 
3 
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| fn aera SE ye Se seceeeses, Stews seeetee a eee less 


* "MEDAGetSimTimea” returns the cuxrent simulation time for the given circuit 
tee eee ween = eee ow oe er oe oe eo rn re 2 re ee ee eeseses= 

*/ 

PQUALIPIER tTime MEDAGstSimfime( pICircuit circuit ); 


[Wewnnn anew nn ee nnn nnn nnn nnn ne nn nnn nnn nn nn nn enn nn nnn nn nn nn nner nner enna 


we wee ew wo a ne ee ee ee ee ee ee ee ee en eer 8 ee 


“MEDARunSimStep” runs the simulation for one time step, i.e. 
all events having the same time as the event at the front of 
the event queue are removed fram the queue and evaluated. 





* 
Return valce none 
* 
Parameters 
* 
circuit A peiunter to the circuit whose simulation 18 
to 2e mun 
paused TRUE means that the “current time" should NOT 


rhs 


be advanced after events are evaluated. Thi 

is used to bring signal values up to date after 

a Carcu.t change without affecting the simulation 

tame. FALSE advances time to the time of the 

next event on the queue. 
teen eee ewe oe ee ee ee on ee ee ee ewe ne ene en sees eo ee eres 
*/ 
PQUALIPIER void MEDARunS.mStep( pICircuit circuit, 

Boolean paused ); 





“MEDAClearSim" clears ail events from the queue, resets 
time to zero and tlegs all devicea in the circuit for 


re-evaluation. 
* 
Return value nene 
* 
Parameters 
* 
circuit A po.nter to the circuit whose simulation is 
tc be run 
resetCliocks TRUE means that an initial event shouic be set 


up for all clock generators in the circuit. 
This shoule be FALSE if the caller hae already 
made arrangements for clocks (e.g. if restoring 
& pre-existing set of events) 





PF eee ew we. 
*/ 
PQUALIFIER void MEDACLearSin( pICircuit circuit, 
tTime time, 
Boolean resetClocks }; 
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EDATiming Library 


Appendix G - The M 








*MEDATimingAvailable” determines whether the timing diagram module 
is available, i.e. whether any of the other calls in this 

library will succeed. Since the user can configure a system 
without the timing module, it is important to make thie cali 
before assuming that any of the other “MEDATiming™ calls 

will work. If this returns FALSE, and you need other calls 

to proceed it is up to you to put up an appropriate error 

box and bail out gracefully. 


° 
RETURN VALUE TRUE if MEDATiming is available, 
FALSE otherwise. 
. 
PARAMETERS 
* 
none 
Pee eee nese == = = 2 2 3 2 oo == === oi iat rt ca naeinnii es aici a 
*/ 
PQUALIFIER Boolean MEDATiningAvailable(}; 
[tewncnnn sens nnnceceoe panniers lca op eps i ja catia i pea saa een tacoma ae 


* “MEDARedrawlimingStatus” updates the tool palette in the timing 
* window for the given circuit a0 it reflects a new status setting 


* 
Return value none 
* 
Parameters 
* 
circuit Pointer to the circuit in question 
tT emo ween ee ewes a eee ewe 9 a ee ee ees eee sess on ae ee eee eee 
*/ 


PQUALIFIER void MEDARedrawTimin Statue(piCireuit circuit); 


* "MEDAPlotTiming” infoxms the timing diagram manager that one or more 
* signals have changed state and time has advanced so the leading edge 
* of the timing diagram needs to be updated. Thie does not update 

* the whole timing window. 
* 


Return value noms 
Y* 
Parametezs 
. 
circuit Pointer to the circuit in queation 
Fe wee eee eee oem een a eee wee Re eRe See Ree errors —— a ———— .-—-== - 
«/ 
PQUALIFIER void MEDAPLotTiming(piCircuit circuit); 


[*anmewenconeee ent i ni ci ee oanenn ees = === 
* "MEDAInitTiming” informa the timing diagram manager that the circuit 
* has been modified in a way that may affect the timing diagram. 


* 
Return value none 
* 
Paraneters 
* 
circuit Pointer to the circuit in question 
Vee eee ee ee eee eee eee ee ee ee ee ee ee ee ee ee 
*/ 


PQUALIFIER void MEDAIn.tTiming(pTCircust circuit); 


$415 


[tewwnn nen en ene ene ene nww cee ne nen ane cn wan eon emnmnw enemas enne——-- se eeeecennn 
* “MEDADisplaySig”" sets the “display in timing diagram" status 
* of the given aignal. If the a.gnal is unnamed, nothing is done. 


f 
PQUALIFIZR void MEDAD:aplaySig(picizcuit pCircuic, 





Boolean display); 
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Appendix H - The MEDAWindows Library 


ftvacese Sie i nein asi pl Se we Gace i ot cs Nai tw iho ipo me ro cokiia aaa am 
e “MEDAAddWindow” adds the Mac window given to the GateXeeper's window list. 
* This has the following effects: 
2 
* ~ the window's title appears in the Window menu 
* - any Toolbox events received by the GateKeeper for the 
* window can be passed on to the module 
* - scroll bar hita and hiliting are handled by the Gatekeeper 
* 
« Parameters 
* 
* window Pointer to Mac window record 
* LinitRect Minimum (tooLeft) and maximum (botRight) 
* size for window 
x hScroll 
bad vScroll handles to the horizontal and vertical scroll bars 
* to be handled by the system 
* refCcon An address to be placed in the "abjRefCon” field 
* o= any notification mesaage relating to thia window 
bad grow TRUE if the GateKaeper should draw a grcow icon 
2 and handle window growing 
* contUpdate TRUE if the GateKeeper should update controls 
* contMsg TRUE if the GateKeeper should check for control 
if hits and send Ws messages instead of just mouse downs 
* msgMask A notification mask of messages the module wants 
* to receive for this window. An empty atring 
* means pase all massages. 
Rema wew eo ono ee ow oe oe ew ow ee ee ee ee Oe a a oe a ae a oe ee ee oe _ 
*/ 
PQUALIFIER void MEDAAddWindow( WandowPtr window, 
Rect limitRect, 
Per nScroll, 
Ptr vScroll, 
PULr vefCon, 
Boolean grow, 
Boolean contUpdate, 
Boolean contMsg, 
char *msgMask }; 
Fe a ar ae a ee wish iti eaieee ct esa is a ee iidsinin 
* "MEDARemoveWindow" removes the given window from the GateKeeper's 
* window list 
2 eee eee ew mee ewe eeee es eeeeeeeeeesseseceers een a one ee ee ee ee eee HS eee eee eee 
«/ 
PQUALIFIER void MEDARemoveWindow( WindowPtr window ); 
[*=------------ eh ae it ap nin a Fe ce Peete en eee SE OE, ta pansies sit ccc 
* “MEDAWindowExtent” returns the largest rectangle on the screen not 
* covered by any window 
Yow ee eee eee een ee AE EE SE eee ee er eee 
+/ 
PQUALIFIER void MEDAWindowExtent{ /*VAR"/ Rect ‘rect ); 
[*a--------------- Bes cecabnia waatadeencudewencccccis ceca wn sce nboaeeseeancee ses one 
* "MEDASetScrollBarHilite” sets the scroll bar active status for the 
* given window. This information is used to determine how a 
* scroll bar is hilited on any update or activate event 
oe eee ned tanita tein tated Et eS ee ee a ee a ke ee me —_ 
*/ 
PQUALIFIER void MEDASetScrollSarhilite( WindowPtr window, 
Boolean vert, 


Boolean active }} 
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MEDA Developer's Kit 2.5b1 
October 4, 1990 
What you have received: 


The enclosed materials comprise a beta release of the MEDA Developer's Kit, 
allowing you to write modules that interface directly with DesignWorks. All 
purchasers of this version will receive a free upgrade to the final release 
version. 


Please note the following important warnings before proceeding: 


+ this is a DEVELOPMENT RELEASE, which means that it almost certainly 
has bugs in it and it is not polished or documented for final release to end 
users. 

« do not distribute the modules you produce with this version very widely. 
We are still making minor changes to the MEDA interface and it is likely that 
modules produced with this version will have to be recompiled to remain 
compatible with the final release. 

+ don't trust the paper documentation too much as it has not been carefully 
checked. It should be considered only an introduction. The comments in the 
example and header files are probably more accurate. 

* the MEDA interface has been changed since the DesignWorks 2.5.2 
version and you MUST use the DesignWorks version included with this 
MEDA Developer's Kit for the modules to work. 


Please consult the "Read Me First" file on Disk #1 before proceeding. It may 


contain notes on manual errata and other up-to-date information on this 
release. 


501 — 1168 Hamilton Street, Vancouver, B.C., Canada V6B 2S2_ Tel: (604) 669-6343 Fax: (604) 669-9531 





IMPORTANT: By opening this package you indicate your 
acceptance of the following License Agreement. 








MEDA Developer's Kit License Agreement 


The information in the MEDA Developer's Kit manuals are subject to change without notice and do not represent a 
commitment on the part of Capilano Computing Systems Ltd. or any employee or agent. 


Software License 


1) The purchaser of the MEDA Developer's Kit package has purchased the physical materials in the package and a 
non-exclusive license to use the software on a single computer. The software may be moved to any other computer 
provided it is used and stored on only one machine at any one time. The purchaser may not provide copies of the 
software to any other party by whatever transmission technology whatsoever. If used on a network system, the 
purchaser must take steps to ensure that the software is used on only one CPU at any one time, and that the 
software is not accessible for copying by other network users. Failure to take these steps may make the purchaser 
tiable for lost income and damages to Capilano Computing Systems Ltd. 


2) The purchaser is permitted to make a reasonable number of copies of the original diskettes and related materials 
for backup purposes only. Ail copyright notices on the original materials must be reproduced on all copies. 


3) The purchaser may seil the license to use the software, along with the original diskettes and ali backup copies to a 
third party. That party is then bound by these same license restrictions. 


4) The program, documentation and related materials are Copyrighted. Any copying of these materials other than as 
permitted by this agreement is in violation of the law. The software and documentation may not ba modified, 
translated into other languages, or reduced to any electronic medium without prior written consent from Capilano 
Computing Systems Ltd. 


5) The purchaser is licensed to incorporate the object code libraries provided into executable code modules and to 
distribute such executable code modules freely. The source, object or executable code provided with this package 
may not be distributed, only the executable code resulting from linking the abject modules provided. 


6) This package is sold only to licensed owners of the DesignWorks, and certain programs and code moduiss 
included with this package are considered upgrades to DesignWorks and are thus covered by the DesignWorks 
License Agreement. 


7) This license agreement is effective until terminated, either by returning all original materials and copies to Capilano 
Computing Systems Ltd., or by destroying all such materials and copies. 


Limitation of Liability and Warranty 


This software and documentation is provided “as is" without any claim as to its suitability for any particular purpose. 
Capilano Computing Systems Ltd. assumes no liability for any loss or injury arising in relation to the use of this 
software or related materials. 


In no event will Capilano Computing Systems Ltd. be liable for any direct, indirect, special, incidental or 

consequential damages resulting from any defect in the software or its documentation. Capilano Computing Systems 
Ltd. will not be liable for loss of any programs or data resulting from the use of the software, or for any costs incurred 
in recovering lost programs or data. 


The sole warranty provided is that the original diskette and related documentation will be free from defects in 
materials or workmanship. Any defective original diskette returned to Capilano Computing Systems Ltd. by the 
original purchaser within 90 days of purchase will be replaced free of charge. 


Some jurisdictions do not allow the exclusion or limitation of implied warranties or liability, so some of the preceding 
clauses may not apply to you. If any clause in this agreement is found to be void, illegal or unenforcable in your 
jurisdiction then that clause shall be considered severed and the remaining clauses shall continue to be valid. 


Should you have any questions about this license agreement or the DesignWorks product, contact us at: Capilano 
Computing Systems Ltd., 501 - 1168 Hamilton Street, Vancouver, B. C., Canada, V6B 2S2, Phone (604) 669-6343 
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